Open311

Wiki

Collaboration for an Open311 Standard
Personal tools

Difference between revisions of "GeoReport v2 Draft"

Collaboration for an Open311 Standard

Jump to: navigation, search
(→‎Retrieve Requests: clarify optional args for feed requests)
(Rolling v2.1 drafting page back into main v2 space. Changes documented at http://wiki.open311.org/Talk:GeoReport_v2.1_Draft)
Line 1: Line 1:
 
The GeoReport API allows developers to build applications to report non-emergency issues such as graffiti, potholes, and street cleaning directly to government organizations like cities.  
 
The GeoReport API allows developers to build applications to report non-emergency issues such as graffiti, potholes, and street cleaning directly to government organizations like cities.  
  
−
==Internationalization==
+
==Internationalization and Encoding==
  
 
=== Date/time format ===
 
=== Date/time format ===
Line 8: Line 8:
  
 
Examples:   
 
Examples:   
 +
* 1994-11-05T08:15:30-05:00 corresponds to November 5, 1994, 8:15:30 am, US Eastern Standard Time.
 +
* 1994-11-05T13:15:30Z corresponds to the same instant.
  
−
1994-11-05T08:15:30-05:00 corresponds to November 5, 1994, 8:15:30 am, US Eastern Standard Time.
+
===Encoding===
 +
UTF-8 is required everywhere.  
  
−
1994-11-05T13:15:30Z corresponds to the same instant.
+
All text returned by the service, whether in XML, JSON, or any other text-based content-type, MUST be encoded as UTF-8. Appropriate HTTP headers must be set, and the XML root element must contain the appropriate encoding="UTF-8" attribute. All text received by the service from the client will be assumed to be UTF-8 and must be decoded accordingly.
  
−
===Character encoding===
 
−
 
−
UTF8 must be used as the character encoding.
 
  
 
==Definitions==
 
==Definitions==
Line 25: Line 25:
 
==API methods==
 
==API methods==
  
−
===service_list===
+
===GET Service List===
 
*'''Purpose:''' provide a list of acceptable 311 services and associated service code
 
*'''Purpose:''' provide a list of acceptable 311 services and associated service code
−
*'''Method name:''' service_list
+
* '''URL:'''https://open311.sfgov.org/dev/v2/services.[format]
−
* '''URL:'''https://open311.sfgov.org/dev/v2/service_list.[format]
+
*'''Sample URL:''' https://open311.sfgov.org/dev/v2/services.xml?jurisdiction_id=sfgov.org
−
*'''Sample URL:''' https://open311.sfgov.org/dev/v2/service_list.xml?api_key=xyz&jurisdiction_id=sfgov.org
+
 
*'''Formats: '''xml
 
*'''Formats: '''xml
 
*'''HTTP Method: '''GET
 
*'''HTTP Method: '''GET
 
*'''Requires API Key: '''No
 
*'''Requires API Key: '''No
 
*'''Arguments: '''
 
*'''Arguments: '''
−
** api_key
 
 
** jurisdiction_id (for SF = sfgov.org)
 
** jurisdiction_id (for SF = sfgov.org)
 
*'''Response:'''
 
*'''Response:'''
 
** service_name
 
** service_name
 
** service_code
 
** service_code
−
** service_description
+
** description (was service_description)
−
** service_metadata (Y = need to make service_defintion call, N = do not make service_definition call)
+
** group (to let developers group similar request types) - may be blank
 +
** keywords (to allow for associations with similar words) - may be blank
 +
** metadata (true = need to make service_defintion call, false = do not make service_definition call)
 +
** type (realtime = service request ID returned immediately, batch = token will be returned, blackbox = no tracking of service requests)
 +
 
 +
*  '''Possible Errors''' (with HTTP status codes)
 +
**  408 - General service error  (Anything that fails during service list processing. The client will need to notify us)  
  
 
'''Example response:'''
 
'''Example response:'''
  
 
<pre class="brush:xml">
 
<pre class="brush:xml">
−
 
+
<services>
−
<service_response>
+
<service>
−
<open311_service_list>
+
<service_code >001</service_code >
−
<service service_code="001" service_name="Cans left out 24x7" service_description="Garbage or recycling cans that have been left out for more than 24 hours after collection. Violators will be cited. "/>
+
<metadata>true</metadata>
−
<service service_code="002" service_name="Construction plate shifted" service_description="Metal construction plate covering the street or sidewalk has been moved. "/>
+
<type>realtime</type>
−
<service service_code="003" service_name="Curb or curb ramp defect" service_description="Sidewalk curb or ramp has problems such as cracking, missing pieces, holes, and/or chipped curb. "/>
+
<keywords>lorem, ipsum, dolor</keywords>
−
<service service_code="004" service_name="Damaged city can" service_description="Damage to a city garbage receptacle such as missing parts (lid, door, liner) or other physical damage. "/>
+
<group>sanitation</group>
−
<service service_code="005" service_name="Damaged side sewer vent cover" service_description="Damage to a side sewer vent cover with problems such as cracking, bending, rusting, or denting"/>
+
<service_code>Cans left out 24x7</service_code>
−
<service service_code="006" service_name="Damaged tree" service_description="Damage to a city maintained tree. To check whether a tree is city maintained: http://bit.ly/6hsDk1"/>
+
<description>Garbage or recycling cans that have been left out for more than 24 hours after collection. Violators will be cited.</description>
−
<service service_code="007" service_name="Graffiti on bike rack - not offensive" service_description="Graffiti on a bike rack that does not contain racial slurs, profanity, or gang related language"/>
+
</service>
−
<service service_code="008" service_name="Graffiti on news rack - not offensive" service_description="Graffiti on a news rack that does not contain racial slurs, profanity, or gang related language "/>
+
<service>
−
<service service_code="009" service_name="Graffiti on parking meter - not offensive" service_description="Graffiti on a parking meter that does not contain racial slurs, profanity, or gang related language "/>
+
<service_code >002</service_code >
−
<service service_code="010" service_name="Graffiti on pay phone - not offensive" service_description="Graffiti on a pay phone that does not contain racial slurs, profanity, or gang related language.  "/>
+
<metadata>true</metadata>
−
<service service_code="011" service_name="Graffiti on private property - not offensive" service_description="Graffiti on a privately owned building or structure that does not contain racial slurs, profanity, or gang related language  "/>
+
<type>realtime</type>
−
<service service_code="012" service_name="Graffiti on private property - offensive" service_description="Graffiti on a privately owned building or structure that contains racial slurs, profanity, or gang related language "/>
+
<keywords>lorem, ipsum, dolor</keywords>
−
<service service_code="013" service_name="Graffiti on public property - offensive" service_description="Graffiti on public property (building, pole, sidewalk, hydrant, etc) with racial slurs, profanity, or gang related language "/>
+
<group>street</group>
−
<service service_code="014" service_name="Graffiti on public property- not offensive" service_description="Graffiti on public property (building, pole, sidewalk, hydrant, etc) without racial slurs, profanity, or gang related language  "/>
+
<service_code>Construction plate shifted</service_code>
−
<service service_code="015" service_name="Illegal dumping" service_description="Identify someone that has dumped or is dumping furniture or garbage onto the street or sidewalk. Violators will be cited "/>
+
<description>Metal construction plate covering the street or sidewalk has been moved.</description>
−
<service service_code="016" service_name="Landscaping request" service_description="Request maintenance on public property (except on park property) such as lawn mowing, bush or strip trimming and removal "/>
+
</service>
−
<service service_code="017" service_name="Missed route - mechanical sweeping" service_description="Street cleaning sweeper did not show up as scheduled according to the street cleaning signs "/>
+
<service>
−
<service service_code="018" service_name="Missing side sewer vent cover" service_description="The 4" side sewer vent cover (http://bit.ly/57BlOv) is missing from the sidewalk  "/>
+
<service_code >003</service_code >
−
<service service_code="019" service_name="Overflowing city receptacle or dumpster" service_description="City receptacle is overflowing and/or has garbage on and around the container "/>
+
<metadata>true</metadata>
−
<service service_code="020" service_name="Overgrown tree" service_description="Request that a city maintained tree (except on park property) be trimmed.  To check whether a tree is city maintained: http://bit.ly/6hsDk1 "/>
+
<type>realtime</type>
−
<service service_code="021" service_name="Pothole in Street" service_description="Defect on the street such as broken, cracked, and sinking asphalt or concrete "/>
+
<keywords>lorem, ipsum, dolor</keywords>
−
<service service_code="022" service_name="Sewage coming out of catch basin" service_description="Sewage or dirty water coming out of a catchbasin (located at the corner of intersections) "/>
+
<group>street</group>
−
<service service_code="023" service_name="Water coming from side sewer" service_description="Sewage or odor coming out of a 4" side sewer (http://bit.ly/57BlOv) located on the sidewalk "/>
+
<service_code>Curb or curb ramp defect</service_code>
−
<service service_code="024" service_name="Sidewalk cleaning" service_description="Have garbage or human waste removed from the sidewalk and/or request services such as steam cleaning of sidewalks "/>
+
<description>Sidewalk curb or ramp has problems such as cracking, missing pieces, holes, and/or chipped curb.</description>
−
<service service_code="025" service_name="Sidewalk defect" service_description="Defect on the sidewalk such as broken, cracked, and/or sinking concrete "/>
+
</service>
−
<service service_code="026" service_name="Street cleaning" service_description="Request to have garbage or human waste removed from the street "/>
+
<service>
−
<service service_code="027" service_name="Tree damaging property" service_description="Tree is damaging property (except for parks) or housing structure. City will address problem if it is a city maintained tree otherwise the property owner is notified to correct the issue "/>
+
<service_code >004</service_code >
−
<service service_code="028" service_name="Water main break" service_description="Street is flooding due to water coming from within the asphalt or from a catchbasin "/>
+
<metadata>true</metadata>
−
<service service_code="029" service_name="Graffiti on street sign" service_description="Graffiti on a street sign such as a stop sign, street name, and/or other parking and traffic signs "/>
+
<type>realtime</type>
−
<service service_code="030" service_name="Odor coming from Side Sewer" service_description="Odor coming out of a 4" side sewer (http://bit.ly/57BlOv) located on the sidewalk.  "/>
+
<keywords>lorem, ipsum, dolor</keywords>
−
<service service_code="031" service_name="Sewage coming out of manhole cover" service_description="Sewage or dirty water coming out of a manhole cover (typically located in the a street or alley) "/>
+
<group>sanitation</group>
−
<service service_code="032" service_name="Sewage coming out of sewer vent" service_description="Sewage or dirty water coming out of a sewer vent (located on the sidewalk) "/>
+
<service_code>Damaged city can</service_code>
−
<service service_code="033" service_name="Pothole in bike lane" service_description="Defect in the bike lane such as broken, cracked, and sinking asphalt or concrete. "/>
+
<description>Damage to a city garbage receptacle such as missing parts (lid, door, liner) or other physical damage.</description>
−
</open311_service_list>
+
</service>
−
<open311_error/>
+
<service>
−
</service_response>
+
<service_code >005</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>sewer</group>
 +
<service_code>Damaged side sewer vent cover</service_code>
 +
<description>Damage to a side sewer vent cover with problems such as cracking, bending, rusting, or denting.</description>
 +
</service>
 +
<service>
 +
<service_code >006</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>tree</group>
 +
<service_code>Damaged tree</service_code>
 +
<description>Damage to a city maintained tree. To check whether a tree is city maintained: http://bit.ly/6hsDk1.</description>
 +
</service>
 +
<service>
 +
<service_code >007</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>graffiti</group>
 +
<service_code>Graffiti on bike rack - not offensive</service_code>
 +
<description>Graffiti on a bike rack that does not contain racial slurs, profanity, or gang related language.</description>
 +
</service>
 +
<service>
 +
<service_code >008</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>graffiti</group>
 +
<service_code>Graffiti on news rack - not offensive</service_code>
 +
<description>Graffiti on a news rack that does not contain racial slurs, profanity, or gang related language .</description>
 +
</service>
 +
<service>
 +
<service_code >009</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>graffiti</group>
 +
<service_code>Graffiti on parking meter - not offensive</service_code>
 +
<description>Graffiti on a parking meter that does not contain racial slurs, profanity, or gang related language .</description>
 +
</service>
 +
<service>
 +
<service_code >010</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>graffiti</group>
 +
<service_code>Graffiti on pay phone - not offensive</service_code>
 +
<description>Graffiti on a pay phone that does not contain racial slurs, profanity, or gang related language.  .</description>
 +
</service>
 +
<service>
 +
<service_code >011</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>graffiti</group>
 +
<service_code>Graffiti on private property - not offensive</service_code>
 +
<description>Graffiti on a privately owned building or structure that does not contain racial slurs, profanity, or gang related language  .</description>
 +
</service>
 +
<service>
 +
<service_code >012</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>graffiti</group>
 +
<service_code>Graffiti on private property - offensive</service_code>
 +
<description>Graffiti on a privately owned building or structure that contains racial slurs, profanity, or gang related language .</description>
 +
</service>
 +
<service>
 +
<service_code >013</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>graffiti</group>
 +
<service_code>Graffiti on public property - offensive</service_code>
 +
<description>Graffiti on public property (building, pole, sidewalk, hydrant, etc) with racial slurs, profanity, or gang related language .</description>
 +
</service>
 +
<service>
 +
<service_code >014</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>graffiti</group>
 +
<service_code>Graffiti on public property- not offensive</service_code>
 +
<description>Graffiti on public property (building, pole, sidewalk, hydrant, etc) without racial slurs, profanity, or gang related language  .</description>
 +
</service>
 +
<service>
 +
<service_code >015</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>sanitation</group>
 +
<service_code>Illegal dumping</service_code>
 +
<description>Identify someone that has dumped or is dumping furniture or garbage onto the street or sidewalk. Violators will be cited .</description>
 +
</service>
 +
<service>
 +
<service_code >016</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>landscaping</group>
 +
<service_code>Landscaping request</service_code>
 +
<description>Request maintenance on public property (except on park property) such as lawn mowing, bush or strip trimming and removal .</description>
 +
</service>
 +
<service>
 +
<service_code >017</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>street</group>
 +
<service_code>Missed route - mechanical sweeping</service_code>
 +
<description>Street cleaning sweeper did not show up as scheduled according to the street cleaning signs .</description>
 +
</service>
 +
<service>
 +
<service_code >018</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>sewer</group>
 +
<service_code>Missing side sewer vent cover</service_code>
 +
<description>The 4 side sewer vent cover (http://bit.ly/57BlOv) is missing from the sidewalk  .</description>
 +
</service>
 +
<service>
 +
<service_code >019</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>sanitation</group>
 +
<service_code>Overflowing city receptacle or dumpster</service_code>
 +
<description>City receptacle is overflowing and/or has garbage on and around the container .</description>
 +
</service>
 +
<service>
 +
<service_code >020</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>tree</group>
 +
<service_code>Overgrown tree</service_code>
 +
<description>Request that a city maintained tree (except on park property) be trimmed.  To check whether a tree is city maintained: http://bit.ly/6hsDk1 .</description>
 +
</service>
 +
<service>
 +
<service_code >021</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>street</group>
 +
<service_code>Pothole in Street</service_code>
 +
<description>Defect on the street such as broken, cracked, and sinking asphalt or concrete .</description>
 +
</service>
 +
<service>
 +
<service_code >022</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>sewer</group>
 +
<service_code>Sewage coming out of catch basin</service_code>
 +
<description>Sewage or dirty water coming out of a catchbasin (located at the corner of intersections) .</description>
 +
</service>
 +
<service>
 +
<service_code >023</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>sewer</group>
 +
<service_code>Water coming from side sewer</service_code>
 +
<description>Sewage or odor coming out of a 4 side sewer (http://bit.ly/57BlOv) located on the sidewalk .</description>
 +
</service>
 +
<service>
 +
<service_code >024</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>sidewalk</group>
 +
<service_code>Sidewalk cleaning</service_code>
 +
<description>Have garbage or human waste removed from the sidewalk and/or request services such as steam cleaning of sidewalks .</description>
 +
</service>
 +
<service>
 +
<service_code >025</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>sidewalk</group>
 +
<service_code>Sidewalk defect</service_code>
 +
<description>Defect on the sidewalk such as broken, cracked, and/or sinking concrete .</description>
 +
</service>
 +
<service>
 +
<service_code >026</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>street</group>
 +
<service_code>Street cleaning</service_code>
 +
<description>Request to have garbage or human waste removed from the street .</description>
 +
</service>
 +
<service>
 +
<service_code >027</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>stree</group>
 +
<service_code>Tree damaging property</service_code>
 +
<description>Tree is damaging property (except for parks) or housing structure. City will address problem if it is a city maintained tree otherwise the property owner is notified to correct the issue .</description>
 +
</service>
 +
<service>
 +
<service_code >028</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>water main</group>
 +
<service_code>Water main break</service_code>
 +
<description>Street is flooding due to water coming from within the asphalt or from a catchbasin .</description>
 +
</service>
 +
<service>
 +
<service_code >029</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>graffiti</group>
 +
<service_code>Graffiti on street sign</service_code>
 +
<description>Graffiti on a street sign such as a stop sign, street name, and/or other parking and traffic signs .</description>
 +
</service>
 +
<service>
 +
<service_code >030</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>sewer</group>
 +
<service_code>Odor coming from Side Sewer</service_code>
 +
<description>Odor coming out of a 4 side sewer (http://bit.ly/57BlOv) located on the sidewalk.  .</description>
 +
</service>
 +
<service>
 +
<service_code >031</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>sewer</group>
 +
<service_code>Sewage coming out of manhole cover</service_code>
 +
<description>Sewage or dirty water coming out of a manhole cover (typically located in the a street or alley) .</description>
 +
</service>
 +
<service>
 +
<service_code >032</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>sewer</group>
 +
<service_code>Sewage coming out of sewer vent</service_code>
 +
<description>Sewage or dirty water coming out of a sewer vent (located on the sidewalk) .</description>
 +
</service>
 +
<service>
 +
<service_code >033</service_code >
 +
<metadata>true</metadata>
 +
<type>realtime</type>
 +
<keywords>lorem, ipsum, dolor</keywords>
 +
<group>street</group>
 +
<service_code>Pothole in bike lane</service_code>
 +
<description>Defect in the bike lane such as broken, cracked, and sinking asphalt or concrete.</description>
 +
</service>
 +
</services>
  
 
</pre>
 
</pre>
  
−
===service_definition===
+
===GET Service Definition===
 
*'''Purpose:''' define attributes associated with a service code
 
*'''Purpose:''' define attributes associated with a service code
−
*'''Method name:''' service_definition
+
*'''URL:''' https://open311.sfgov.org/dev/v2/services/033.[format]
−
*'''URL:''' https://open311.sfgov.org/dev/v2/service_definition.[format]
+
*'''Sample URL:'''https://open311.sfgov.org/dev/v2/service_definition.xml?service_code=DMV66
−
*'''Sample URL:'''https://open311.sfgov.org/dev/v2/service_definition.xml?api_key=xyz&service_code=DMV66
+
 
*'''Formats:''' xml
 
*'''Formats:''' xml
 
*'''HTTP Method:''' GET
 
*'''HTTP Method:''' GET
Line 97: Line 360:
  
 
* Arguments:
 
* Arguments:
−
** api_key
 
 
** service_code
 
** service_code
 +
** jurisdiction_id (for SF = sfgov.org)
  
 
* Response:
 
* Response:
 
**variable
 
**variable
 
**code
 
**code
−
**datatype
+
**datatype (options: string, number, datetime, text, singlevaluelist, multivaluelist)
−
**active
+
**required (true means that the value is required to submit service request)
−
**required
+
 
**datatype_description
 
**datatype_description
 
**order
 
**order
 
**description
 
**description
 
**service_code  
 
**service_code  
 +
**values (provides list of values for singlevaluelist and multivaluelist) - may be empty
  
 
'''Example response:'''
 
'''Example response:'''
  
 
<pre class="brush:xml">
 
<pre class="brush:xml">
−
<service_response>
+
<service_definition>
−
<service_definition>
+
<service_code>DMV66</service_code>
−
<attribute>
+
−
<variable>Y</variable>
+
<attribute>
−
<code>WHISHETN</code>
+
<variable>true</variable>
−
<datatype>CHAR</datatype>
+
<code>WHISHETN</code>
−
<active>N</active>
+
<datatype>singlevaluelist</datatype>
−
<required>N</required>
+
<required>true</required>
−
<datatype_description>N</datatype_description>
+
<datatype_description></datatype_description>
−
<order>N</order>
+
<order>1</order>
−
<description>What is the ticket/tag/DL number?</description>
+
<description>What is the ticket/tag/DL number?</description>
−
<attribute>
+
<values>
−
<service_code>DMV66</service_code>
+
    <value>
−
</service_definition>
+
<key>123</key>
−
</service_response>
+
<name>Ford</name>
 +
</value>
 +
    <value>
 +
<key>124</key>
 +
<name>Chrysler</name>
 +
</value>
 +
</values>
 +
<attribute>
 +
</service_definition>
 
</pre>
 
</pre>
  
−
===Create Request===
+
===POST Service Request===
 
*'''Purpose:''' Create service requests
 
*'''Purpose:''' Create service requests
−
*'''Method name:''' create_request
+
*'''URL:''' https://open311.sfgov.org/dev/v2/requests.[format]
−
*'''URL:''' https://open311.sfgov.org/dev/v2/create_request.[format]
+
*'''Sample URL:'''https://open311.sfgov.org/dev/v2/requests.xml?api_key=xyz&jurisdiction_id=sfgov.org&service_code=001&lat=37.76524078&long=-122.4212043&address_string=xxxx6thstreet&email=smit333@sfgov.edu&device_id=tt222111&account_id=&first_name=jo&last_name=smith&phone=111111111&description=&media_url=http://okgogo.gogo  
−
*'''Sample URL:'''https://open311.sfgov.org/dev/v2/create_request.xml?api_key=xyz&jurisdiction_id=sfgov.org&service_code=001&lat=37.76524078&lon=-122.4212043&address_string=xxxx6thstreet&customer_email=smit333@sfgov.edu&device_id=tt222111&account_id=&first_name=jo&last_name=smith&phone_number=111111111&description=&media_url=http://okgogo.gogo  
+
 
*'''Formats:''' xml
 
*'''Formats:''' xml
 
*'''HTTP Method:''' POST
 
*'''HTTP Method:''' POST
 
*'''Requires API Key:''' Yes
 
*'''Requires API Key:''' Yes
−
*'''Arguments:'''
+
*'''Required Arguments:'''
 
** api_key
 
** api_key
 
** jurisdiction_id
 
** jurisdiction_id
 
** service_code (obtained from method service_list)
 
** service_code (obtained from method service_list)
 +
***
 +
*'''Optional Arguments:'''
 
** lat [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] (required - either lat/lon or address string, both are preferred)
 
** lat [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] (required - either lat/lon or address string, both are preferred)
−
** lon [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] (required - either lat/lon or address string, both are preferred)
+
** long [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] (required - either lat/lon or address string, both are preferred)
 
** address_string (human entered description of location)(if no lat/lon must provide this information)
 
** address_string (human entered description of location)(if no lat/lon must provide this information)
−
** customer_email (optional)
+
** address_id - ID in Master Address Repository
−
** device_id (optional)
+
** email
−
** account_id (optional)
+
** device_id  
−
** first_name (optional)
+
** account_id
−
** last_name (optional)
+
** first_name
−
** phone_number (optional)
+
** last_name  
−
** description (free form limited to 4,000 characters) (optional)
+
** phone
−
** media_url (url to the page that contains the media)(optional)
+
** description (free form limited to 4,000 characters)
 +
** media_url (URL of a page with associated media. This could be an image that should be attached to the report)
  
 
*'''Response: '''
 
*'''Response: '''
 
** service_request_id (may not be returned if token is returned)
 
** service_request_id (may not be returned if token is returned)
 
** token (if returned then use token method)
 
** token (if returned then use token method)
−
** service_level_agreement (may not be returned)
+
** service_notice (may not be returned)
 
** account_id (may not be returned)
 
** account_id (may not be returned)
−
** error codes
+
 
 +
* '''Possible Errors''' (with HTTP status codes)
 +
** 412 - Missing service Code
 +
** 417 - Invalid Service Code
 +
** 408 - General Service Error (Any failure during create request processing, eg CRM is down. Client will need to notify us)
 +
 
 +
 
  
 
'''Example response:'''
 
'''Example response:'''
Line 166: Line 445:
 
<pre class="brush:xml">
 
<pre class="brush:xml">
  
−
<create_response>
+
<service_requests>
−
<open311_error/>
+
  
−
<open311_create>
+
<request>
 
<service_request_id>293944</service_request_id>
 
<service_request_id>293944</service_request_id>
  
−
<service_level_agreement>
+
<service_notice>
 
The City will inspect and require the responsible party to correct within 24 hours and/or issue a Correction Notice or Notice of Violation of the Public Works Code
 
The City will inspect and require the responsible party to correct within 24 hours and/or issue a Correction Notice or Notice of Violation of the Public Works Code
−
</service_level_agreement>
+
</service_notice>
  
 
<account_id/>
 
<account_id/>
  
−
</open311_create>
+
</request>
−
</create_response>
+
−
 
+
<service_requests>
  
 
</pre>
 
</pre>
  
−
===token (GET request_id)===
+
===GET token with request_id===
 
*'''Purpose:''' get the request_id from a temporary token
 
*'''Purpose:''' get the request_id from a temporary token
−
*'''Method name:''' token
+
*'''URL:''' https://open311.sfgov.org/dev/v2/tokens/123456.[format]
−
*'''URL:''' https://open311.sfgov.org/dev/v2/token.[format]
+
*'''Sample URL:'''  https://open311.sfgov.org/dev/v2/tokens/123456.xml?jurisdiction_id=sfgov.org
−
*'''Sample URL:'''  https://open311.sfgov.org/dev/v2/token.xml?token=123456&jurisdiction_id=sfgov.org&api_key=xxxx
+
 
*'''Formats: '''xml
 
*'''Formats: '''xml
 
*'''HTTP Method: '''GET
 
*'''HTTP Method: '''GET
−
*'''Requires API Key: '''Yes
+
*'''Requires API Key: '''No
  
 
*'''Required Arguments: '''
 
*'''Required Arguments: '''
 
** jurisdiction_id
 
** jurisdiction_id
−
** api_key
+
** token
  
 
*'''Response:'''
 
*'''Response:'''
Line 209: Line 486:
 
<request>
 
<request>
 
<service_request_id>638344</service_request_id>
 
<service_request_id>638344</service_request_id>
−
<token>open</token>
+
<token>12345</token>
 
</request>
 
</request>
  
−
<open311_error/>
 
 
</service_requests>
 
</service_requests>
  
 
</pre>
 
</pre>
  
−
 
+
===GET Service Requests===
−
 
+
−
===Retrieve Requests===
+
 
*'''Purpose:''' query the current status of a request
 
*'''Purpose:''' query the current status of a request
−
*'''Method name:''' get_requests
+
*'''URL:''' https://open311.sfgov.org/dev/v2/requests.[format]
−
*'''URL:''' https://open311.sfgov.org/dev/v2/get_requests.[format]
+
*'''Sample URL:'''  https://open311.sfgov.org/dev/v2/requests.xml?service_request_id=293450  
−
*'''Sample URL:'''  https://open311.sfgov.org/dev/v2/get_requests.xml?service_request_id=293450  
+
 
*'''Formats: '''xml
 
*'''Formats: '''xml
 
*'''HTTP Method: '''GET
 
*'''HTTP Method: '''GET
 
*'''Requires API Key: '''No
 
*'''Requires API Key: '''No
 +
 
*'''Required Arguments: '''
 
*'''Required Arguments: '''
−
** none
+
** jurisdiction_id
  
 
*'''Optional Arguments: '''
 
*'''Optional Arguments: '''
 
** service_request_id (can be declared multiple times; overrides all other arguments)
 
** service_request_id (can be declared multiple times; overrides all other arguments)
−
** service_code (defaults to all service codes; can be declared multiple times)
+
** service_code (defaults to all service codes; can be declared multiple times, comma delimited)
 
** start_date & end_date (defaults to most recent 90 days; should not span more than 90 days) (w3 format)
 
** start_date & end_date (defaults to most recent 90 days; should not span more than 90 days) (w3 format)
−
** status (defaults to all statuses)
+
** status (defaults to all statuses; can be declared multiple times, comma delimited; status types are: open, closed)  
 +
 
  
 
*'''Response:'''
 
*'''Response:'''
 
** service_request_id
 
** service_request_id
−
** status
+
** status (open, closed)
 
** status_notes (may not be returned; optional explanation of why status was changed)
 
** status_notes (may not be returned; optional explanation of why status was changed)
 
** service_name
 
** service_name
 
** service_code
 
** service_code
−
** description
+
** description (not all cities return descriptions)
−
** datetime_requested (w3 format)
+
** agency_responsible  (not all cities return agency responsible)
 +
** service_notice (was service_level_agreement; may be blank)
 +
** requested_datetime (w3 format)
 +
** updated_datetime (last time SR was modified, for closed SRs it will be closure date)
 +
** expected_datetime (optional, returns date SR should be closed based on SLA for this service)
 
** address
 
** address
 +
** address_id (not all cities will return address_id, may be blank)
 
** zipcode
 
** zipcode
−
** geo:lat
+
** lat
−
** geo:long
+
** long
 
** georss:point
 
** georss:point
 +
 +
*'''Response Volume'''
 +
** Default query limit is a span of 90 days or first 1000 requests returned, whichever is smallest.
 +
 +
 +
*  '''Possible Errors''' (with HTTP status codes)
 +
**  409 - service_request_id not valid
 +
**  408 - General Service error (Any failure during service query processing. Client will have to notify us)
 +
  
 
'''Example response:'''
 
'''Example response:'''
Line 256: Line 545:
 
<service_requests>
 
<service_requests>
  
−
<request>
+
<request>
−
<service_request_id>638344</service_request_id>
+
<service_request_id>638344</service_request_id>
−
<status>closed</status>
+
<status>closed</status>
−
<status_notes>Duplicate request.</status_notes>
+
<status_notes>Duplicate request.</status_notes>
−
<service_name>Sidewalk and Curb Issues</service_name>
+
<name>Sidewalk and Curb Issues</name>
−
<service_code>006</service_code>
+
<code>006</code>
−
<description></description>
+
<description></description>
−
<datetime_requested>2010-04-14T06:37:38-08:00</datetime_requested>
+
<agency_responsible></agency_responsible>
−
<address>8TH AVE and JUDAH ST</address>
+
<service_notice></service_notice>
−
<zipcode>94122</zipcode>
+
<requested_datetime>2010-04-14T06:37:38-08:00</requested_datetime>
−
<geo:lat xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#">37.762221815</geo:lat>
+
<updated_datetime>2010-04-14T06:37:38-08:00</updated_datetime>
−
<geo:long xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#">-122.4651145</geo:long>
+
<expected_datetime>2010-04-15T06:37:38-08:00</expected_datetime>
−
<georss:point xmlns:georss="http://www.georss.org/georss">37.762221815 -122.4651145</georss:point>
+
<address>8TH AVE and JUDAH ST</address>
−
</request>
+
<address_id>545483</address_id>
 +
<zipcode>94122</zipcode>
 +
<lat>37.762221815</lat>
 +
<long>-122.4651145</long>
 +
<georss:point xmlns:georss="http://www.georss.org/georss">37.762221815 -122.4651145</georss:point>
 +
</request>
  
−
<open311_error/>
 
 
</service_requests>
 
</service_requests>
  
 
</pre>
 
</pre>
  
−
===Error Codes===
+
===General Errors===
  
 
'''Response:'''
 
'''Response:'''
 +
* status code - returned in HTTP header as HTTP status code
 +
* error (description of error)
  
−
* errorCode (may not be returned)
+
* '''General'''
−
* errorDescription (may not be returned)
+
** 400 - Missing API key  
−
 
+
** 401 - Invalid API Key  
−
 
+
** 404 - The URL request is invalid  or open311 service is not running or reachable. Client should notify us after checking URL  
−
 
+
−
* service_list:
+
−
**  100    Missing API Key
+
−
**  101    Invalid APi Key
+
−
**  102    General service error  ( -- Missing service list file , anything that happens during service_list processing. It should be follow by an error description. The client will need to notify us)
+
−
 
+
−
*  create_request
+
−
** 200  Missing API Key
+
−
** 201  Invalid API Key
+
−
** 202  Missing service Code
+
−
** 203  Invalid Service Code
+
−
** 204  General Service Error ( anything captured during create_request processing ,  Lagan WS is down , ....An error description will follow. Client will need to notify us)
+
−
 
+
−
*  status_update
+
−
**  300  Missing API key  
+
−
** 301  Invalid API Key  
+
−
**  302  Id not valid or you are attemting to search for a service request you did not create
+
−
**  302  General Service error ( anything captured during status_update processing. It will always have an error description ..Client will have to notify us) 
+
−
 
+
−
*  HTTP error code: (from the browser). So far I have seen this
+
−
** 404 The URL request is invalid  or open311 service is not running or reachable. Client should notify us after checking URL  
+
−
 
+
−
'''Example error:'''
+
−
 
+
−
Example URL: [https://open311.sfgov.org/dev/v2/create_request?api_key=xyz&jurisdiction_id=sfgov.org&service_code=001&lat=37.76524078&lon=-122.4212043&address_string=xxxx6thstreet&customer_email=smit333@sfgov.edu&device_id=tt222111&account_id=&first_name=jo&last_name=smith&phone_number=111111111&description=&media_url=http://okgogo.gogo https://open311.sfgov.org/dev/v2/create_request?api_key=xyz........]
+
  
 +
'''Example:'''
 
<pre class="brush:xml">
 
<pre class="brush:xml">
 +
HTTP/1.1 401 Unauthorized
  
−
<create_response>
+
<error>Invalid api_key received -- can't proceed with create_request.</error>
−
<open311_error>
+
−
<errorCode>201</errorCode>
+
−
<errorDescription>Invalid api_key received -- can't proceed with create_request.</errorDescription>
+
−
</open311_error>
+
−
<open311_create/>
+
−
</create_response>
+
−
 
+
 
</pre>
 
</pre>
−
 
−
==Query Service Requests==
 
−
 
−
Methods to query services requests have not yet been integrated into the spec. For now there are different options for different cities. Both San Francisco and Washington D.C. provide KML files of all service requests. San Francisco also provides a separate web service for service requests.
 
−
 
−
====San Francisco====
 
−
* [http://apps.sfgov.org/datafiles/index.php?dir=311 KML]
 
−
* [http://apps.sfgov.org/datafiles/view.php?file=311/webservice.txt Guide to RESTful XML Web Service]
 
−
 
−
====Washington D.C.====
 
−
* [http://data.octo.dc.gov/feeds/src/src_current.kml KML]
 
−
* [http://data.octo.dc.gov/feeds/src/src_current.xml XML feed]
 
−
* [http://data.octo.dc.gov/NewCalendar.aspx?datasetid=4 Custom query] also provides Shapefile export
 
−
* [http://data.octo.dc.gov/feeds/src/src_current_plain.zip Plain text .zip]
 
−
* [http://data.octo.dc.gov/feeds/src/src_current_csv.zip Excel CSV]
 
−
* [http://data.octo.dc.gov/Metadata.aspx?id=4 Guide to Metadata]
 
−
 
−
 
−
====Example Queries====
 
−
 
−
====== '''San Francisco'''======
 
−
http://crmproxy.sfgov.org/status/ReportService/ProxyService/ReportCommandHandler?request_type=all&start_date=2010-04-13&end_date=2010-04-14
 
−
 
−
====== '''Washington D.C.'''======
 
−
http://data.octo.dc.gov/Attachment.aspx?where=Police_Dictrict&area=SECOND&what=XML&date=serviceorderdate&from=4/14/2010%2012:00:00%20AM&to=4/15/2010%2011:59:00%20PM&dataset=SRC&datasetid=4&whereInd=3&areaInd=1&whatInd=2&dateInd=0&whenInd=1&disposition=attachment
 

Revision as of 15:01, 6 May 2010

The GeoReport API allows developers to build applications to report non-emergency issues such as graffiti, potholes, and street cleaning directly to government organizations like cities.

Internationalization and Encoding

Date/time format

All date/time fields must be formatted in a common subset of ISO 8601 as per the w3 note. Timezone information (either Z meaning UTC, or an HH:MM offset from UTC) must be included.

Examples:

  • 1994-11-05T08:15:30-05:00 corresponds to November 5, 1994, 8:15:30 am, US Eastern Standard Time.
  • 1994-11-05T13:15:30Z corresponds to the same instant.

Encoding

UTF-8 is required everywhere.

All text returned by the service, whether in XML, JSON, or any other text-based content-type, MUST be encoded as UTF-8. Appropriate HTTP headers must be set, and the XML root element must contain the appropriate encoding="UTF-8" attribute. All text received by the service from the client will be assumed to be UTF-8 and must be decoded accordingly.


Definitions

jurisdiction_id

As a means to allow this API to be used by multiple cities we've included a "jurisdiction_id" which will be the unique identifier for cities. It has been suggested that we use the city's url as the "jurisdiction_id". We have incorporated that suggestion into our design and the jurisdiction_id for San Francisco = sfgov.org


API methods

GET Service List

  • Purpose: provide a list of acceptable 311 services and associated service code
  • URL:https://open311.sfgov.org/dev/v2/services.[format]
  • Sample URL: https://open311.sfgov.org/dev/v2/services.xml?jurisdiction_id=sfgov.org
  • Formats: xml
  • HTTP Method: GET
  • Requires API Key: No
  • Arguments:
    • jurisdiction_id (for SF = sfgov.org)
  • Response:
    • service_name
    • service_code
    • description (was service_description)
    • group (to let developers group similar request types) - may be blank
    • keywords (to allow for associations with similar words) - may be blank
    • metadata (true = need to make service_defintion call, false = do not make service_definition call)
    • type (realtime = service request ID returned immediately, batch = token will be returned, blackbox = no tracking of service requests)
  • Possible Errors (with HTTP status codes)
    • 408 - General service error (Anything that fails during service list processing. The client will need to notify us)

Example response: 

<services>
	<service>
		<service_code >001</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sanitation</group>
		<service_code>Cans left out 24x7</service_code>
		<description>Garbage or recycling cans that have been left out for more than 24 hours after collection. Violators will be cited.</description>
	</service>
	<service>
		<service_code >002</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>street</group>
		<service_code>Construction plate shifted</service_code>
		<description>Metal construction plate covering the street or sidewalk has been moved.</description>
	</service>
	<service>
		<service_code >003</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>street</group>
		<service_code>Curb or curb ramp defect</service_code>
		<description>Sidewalk curb or ramp has problems such as cracking, missing pieces, holes, and/or chipped curb.</description>
	</service>
	<service>
		<service_code >004</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sanitation</group>
		<service_code>Damaged city can</service_code>
		<description>Damage to a city garbage receptacle such as missing parts (lid, door, liner) or other physical damage.</description>
	</service>
	<service>
		<service_code >005</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sewer</group>
		<service_code>Damaged side sewer vent cover</service_code>
		<description>Damage to a side sewer vent cover with problems such as cracking, bending, rusting, or denting.</description>
	</service>
	<service>
		<service_code >006</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>tree</group>
		<service_code>Damaged tree</service_code>
		<description>Damage to a city maintained tree. To check whether a tree is city maintained: http://bit.ly/6hsDk1.</description>
	</service>
	<service>
		<service_code >007</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>graffiti</group>
		<service_code>Graffiti on bike rack - not offensive</service_code>
		<description>Graffiti on a bike rack that does not contain racial slurs, profanity, or gang related language.</description>
	</service>
	<service>
		<service_code >008</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>graffiti</group>
		<service_code>Graffiti on news rack - not offensive</service_code>
		<description>Graffiti on a news rack that does not contain racial slurs, profanity, or gang related language .</description>
	</service>
	<service>
		<service_code >009</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>graffiti</group>
		<service_code>Graffiti on parking meter - not offensive</service_code>
		<description>Graffiti on a parking meter that does not contain racial slurs, profanity, or gang related language .</description>
	</service>
	<service>
		<service_code >010</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>graffiti</group>
		<service_code>Graffiti on pay phone - not offensive</service_code>
		<description>Graffiti on a pay phone that does not contain racial slurs, profanity, or gang related language.  .</description>
	</service>
	<service>
		<service_code >011</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>graffiti</group>
		<service_code>Graffiti on private property - not offensive</service_code>
		<description>Graffiti on a privately owned building or structure that does not contain racial slurs, profanity, or gang related language  .</description>
	</service>
	<service>
		<service_code >012</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>graffiti</group>
		<service_code>Graffiti on private property - offensive</service_code>
		<description>Graffiti on a privately owned building or structure that contains racial slurs, profanity, or gang related language .</description>
	</service>
	<service>
		<service_code >013</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>graffiti</group>
		<service_code>Graffiti on public property - offensive</service_code>
		<description>Graffiti on public property (building, pole, sidewalk, hydrant, etc) with racial slurs, profanity, or gang related language .</description>
	</service>
	<service>
		<service_code >014</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>graffiti</group>
		<service_code>Graffiti on public property- not offensive</service_code>
		<description>Graffiti on public property (building, pole, sidewalk, hydrant, etc) without racial slurs, profanity, or gang related language  .</description>
	</service>
	<service>
		<service_code >015</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sanitation</group>
		<service_code>Illegal dumping</service_code>
		<description>Identify someone that has dumped or is dumping furniture or garbage onto the street or sidewalk. Violators will be cited .</description>
	</service>
	<service>
		<service_code >016</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>landscaping</group>
		<service_code>Landscaping request</service_code>
		<description>Request maintenance on public property (except on park property) such as lawn mowing, bush or strip trimming and removal .</description>
	</service>
	<service>
		<service_code >017</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>street</group>
		<service_code>Missed route - mechanical sweeping</service_code>
		<description>Street cleaning sweeper did not show up as scheduled according to the street cleaning signs .</description>
	</service>
	<service>
		<service_code >018</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sewer</group>
		<service_code>Missing side sewer vent cover</service_code>
		<description>The 4 side sewer vent cover (http://bit.ly/57BlOv) is missing from the sidewalk  .</description>
	</service>
	<service>
		<service_code >019</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sanitation</group>
		<service_code>Overflowing city receptacle or dumpster</service_code>
		<description>City receptacle is overflowing and/or has garbage on and around the container .</description>
	</service>
	<service>
		<service_code >020</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>tree</group>
		<service_code>Overgrown tree</service_code>
		<description>Request that a city maintained tree (except on park property) be trimmed.  To check whether a tree is city maintained: http://bit.ly/6hsDk1 .</description>
	</service>
	<service>
		<service_code >021</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>street</group>
		<service_code>Pothole in Street</service_code>
		<description>Defect on the street such as broken, cracked, and sinking asphalt or concrete .</description>
	</service>
	<service>
		<service_code >022</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sewer</group>
		<service_code>Sewage coming out of catch basin</service_code>
		<description>Sewage or dirty water coming out of a catchbasin (located at the corner of intersections) .</description>
	</service>
	<service>
		<service_code >023</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sewer</group>
		<service_code>Water coming from side sewer</service_code>
		<description>Sewage or odor coming out of a 4 side sewer (http://bit.ly/57BlOv) located on the sidewalk .</description>
	</service>
	<service>
		<service_code >024</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sidewalk</group>
		<service_code>Sidewalk cleaning</service_code>
		<description>Have garbage or human waste removed from the sidewalk and/or request services such as steam cleaning of sidewalks .</description>
	</service>
	<service>
		<service_code >025</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sidewalk</group>
		<service_code>Sidewalk defect</service_code>
		<description>Defect on the sidewalk such as broken, cracked, and/or sinking concrete .</description>
	</service>
	<service>
		<service_code >026</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>street</group>
		<service_code>Street cleaning</service_code>
		<description>Request to have garbage or human waste removed from the street .</description>
	</service>
	<service>
		<service_code >027</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>stree</group>
		<service_code>Tree damaging property</service_code>
		<description>Tree is damaging property (except for parks) or housing structure. City will address problem if it is a city maintained tree otherwise the property owner is notified to correct the issue .</description>
	</service>
	<service>
		<service_code >028</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>water main</group>
		<service_code>Water main break</service_code>
		<description>Street is flooding due to water coming from within the asphalt or from a catchbasin .</description>
	</service>
	<service>
		<service_code >029</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>graffiti</group>
		<service_code>Graffiti on street sign</service_code>
		<description>Graffiti on a street sign such as a stop sign, street name, and/or other parking and traffic signs .</description>
	</service>
	<service>
		<service_code >030</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sewer</group>
		<service_code>Odor coming from Side Sewer</service_code>
		<description>Odor coming out of a 4 side sewer (http://bit.ly/57BlOv) located on the sidewalk.  .</description>
	</service>
	<service>
		<service_code >031</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sewer</group>
		<service_code>Sewage coming out of manhole cover</service_code>
		<description>Sewage or dirty water coming out of a manhole cover (typically located in the a street or alley) .</description>
	</service>
	<service>
		<service_code >032</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sewer</group>
		<service_code>Sewage coming out of sewer vent</service_code>
		<description>Sewage or dirty water coming out of a sewer vent (located on the sidewalk) .</description>
	</service>
	<service>
		<service_code >033</service_code >
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>street</group>
		<service_code>Pothole in bike lane</service_code>
		<description>Defect in the bike lane such as broken, cracked, and sinking asphalt or concrete.</description>
	</service>
</services>

GET Service Definition

  • Arguments:
    • service_code
    • jurisdiction_id (for SF = sfgov.org)
  • Response:
    • variable
    • code
    • datatype (options: string, number, datetime, text, singlevaluelist, multivaluelist)
    • required (true means that the value is required to submit service request)
    • datatype_description
    • order
    • description
    • service_code
    • values (provides list of values for singlevaluelist and multivaluelist) - may be empty

Example response: 

<service_definition>
	<service_code>DMV66</service_code>
	
	<attribute>
		<variable>true</variable>
		<code>WHISHETN</code>
		<datatype>singlevaluelist</datatype>
		<required>true</required>
		<datatype_description></datatype_description>		
		<order>1</order>	
		<description>What is the ticket/tag/DL number?</description>
		<values>
		    <value>
			 	<key>123</key>
				<name>Ford</name>
			</value>
		    <value>
			 	<key>124</key>
				<name>Chrysler</name>
			</value>			
		</values>
	<attribute>	
</service_definition>

POST Service Request

  • Response:
    • service_request_id (may not be returned if token is returned)
    • token (if returned then use token method)
    • service_notice (may not be returned)
    • account_id (may not be returned)
  • Possible Errors (with HTTP status codes)
    • 412 - Missing service Code
    • 417 - Invalid Service Code
    • 408 - General Service Error (Any failure during create request processing, eg CRM is down. Client will need to notify us)


Example response: 


<service_requests>

	<request>
		<service_request_id>293944</service_request_id>

		<service_notice>
			The City will inspect and require the responsible party to correct within 24 hours and/or issue a Correction Notice or Notice of Violation of the Public Works Code
		</service_notice>

		<account_id/>

	</request>
	
<service_requests>

GET token with request_id

  • Required Arguments:
    • jurisdiction_id
    • token
  • Response:
    • service_request_id
    • token

Example response: 


<service_requests>

	<request>
		<service_request_id>638344</service_request_id>
		<token>12345</token>
	</request>

</service_requests>

GET Service Requests

  • Required Arguments:
    • jurisdiction_id
  • Optional Arguments:
    • service_request_id (can be declared multiple times; overrides all other arguments)
    • service_code (defaults to all service codes; can be declared multiple times, comma delimited)
    • start_date & end_date (defaults to most recent 90 days; should not span more than 90 days) (w3 format)
    • status (defaults to all statuses; can be declared multiple times, comma delimited; status types are: open, closed)


  • Response:
    • service_request_id
    • status (open, closed)
    • status_notes (may not be returned; optional explanation of why status was changed)
    • service_name
    • service_code
    • description (not all cities return descriptions)
    • agency_responsible (not all cities return agency responsible)
    • service_notice (was service_level_agreement; may be blank)
    • requested_datetime (w3 format)
    • updated_datetime (last time SR was modified, for closed SRs it will be closure date)
    • expected_datetime (optional, returns date SR should be closed based on SLA for this service)
    • address
    • address_id (not all cities will return address_id, may be blank)
    • zipcode
    • lat
    • long
    • georss:point
  • Response Volume
    • Default query limit is a span of 90 days or first 1000 requests returned, whichever is smallest.


  • Possible Errors (with HTTP status codes)
    • 409 - service_request_id not valid
    • 408 - General Service error (Any failure during service query processing. Client will have to notify us)


Example response: 


<service_requests>

<request>
	<service_request_id>638344</service_request_id>
	<status>closed</status>
	<status_notes>Duplicate request.</status_notes>
	<name>Sidewalk and Curb Issues</name>
	<code>006</code>
	<description></description>
	<agency_responsible></agency_responsible>
	<service_notice></service_notice>
	<requested_datetime>2010-04-14T06:37:38-08:00</requested_datetime>
	<updated_datetime>2010-04-14T06:37:38-08:00</updated_datetime>
	<expected_datetime>2010-04-15T06:37:38-08:00</expected_datetime>
	<address>8TH AVE and JUDAH ST</address>
	<address_id>545483</address_id>
	<zipcode>94122</zipcode>
	<lat>37.762221815</lat>
	<long>-122.4651145</long>
	<georss:point xmlns:georss="http://www.georss.org/georss">37.762221815 -122.4651145</georss:point>
</request>

</service_requests>

General Errors

Response:

  • status code - returned in HTTP header as HTTP status code
  • error (description of error)
  • General
    • 400 - Missing API key
    • 401 - Invalid API Key
    • 404 - The URL request is invalid or open311 service is not running or reachable. Client should notify us after checking URL

Example: 

HTTP/1.1 401 Unauthorized 

<error>Invalid api_key received -- can't proceed with create_request.</error>
Retrieved from "https://wiki-archive.open311.org/index.php?title=GeoReport_v2_Draft&oldid=536"