|
|
| Line 1: |
Line 1: |
| − | For the stable v2 spec, see [[GeoReport v2]]
| + | #REDIRECT [[GeoReport_v2_Draft]] |
| − | | + | |
| − | | + | |
| − | 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 [http://www.w3.org/TR/NOTE-datetime 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:'''
| + | |
| − | | + | |
| − | <pre class="brush:xml">
| + | |
| − | <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>
| + | |
| − | | + | |
| − | </pre>
| + | |
| − | | + | |
| − | ===GET Service Definition===
| + | |
| − | *'''Purpose:''' define attributes associated with a service code
| + | |
| − | *'''URL:''' https://open311.sfgov.org/dev/v2/services/033.[format]
| + | |
| − | *'''Sample URL:'''https://open311.sfgov.org/dev/v2/service_definition.xml?service_code=DMV66
| + | |
| − | *'''Formats:''' xml
| + | |
| − | *'''HTTP Method:''' GET
| + | |
| − | *'''Requires API Key:''' No
| + | |
| − | | + | |
| − | * 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:'''
| + | |
| − | | + | |
| − | <pre class="brush:xml">
| + | |
| − | <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>
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | ===POST Service Request===
| + | |
| − | *'''Purpose:''' Create service requests
| + | |
| − | *'''URL:''' https://open311.sfgov.org/dev/v2/requests.[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
| + | |
| − | *'''Formats:''' xml
| + | |
| − | *'''HTTP Method:''' POST
| + | |
| − | *'''Requires API Key:''' Yes
| + | |
| − | *'''Required Arguments:'''
| + | |
| − | ** api_key
| + | |
| − | ** jurisdiction_id
| + | |
| − | ** 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)
| + | |
| − | ** 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_id - ID in Master Address Repository
| + | |
| − | ** email
| + | |
| − | ** device_id
| + | |
| − | ** account_id
| + | |
| − | ** first_name
| + | |
| − | ** last_name
| + | |
| − | ** phone
| + | |
| − | ** 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: '''
| + | |
| − | ** 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:'''
| + | |
| − | | + | |
| − | <pre class="brush:xml">
| + | |
| − | | + | |
| − | <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>
| + | |
| − | | + | |
| − | </pre>
| + | |
| − | | + | |
| − | ===GET token with request_id===
| + | |
| − | *'''Purpose:''' get the request_id from a temporary token
| + | |
| − | *'''URL:''' https://open311.sfgov.org/dev/v2/tokens/123456.[format]
| + | |
| − | *'''Sample URL:''' https://open311.sfgov.org/dev/v2/tokens/123456.xml?jurisdiction_id=sfgov.org
| + | |
| − | *'''Formats: '''xml
| + | |
| − | *'''HTTP Method: '''GET
| + | |
| − | *'''Requires API Key: '''No
| + | |
| − | | + | |
| − | *'''Required Arguments: '''
| + | |
| − | ** jurisdiction_id
| + | |
| − | ** token
| + | |
| − | | + | |
| − | *'''Response:'''
| + | |
| − | ** service_request_id
| + | |
| − | ** token
| + | |
| − | | + | |
| − | '''Example response:'''
| + | |
| − | | + | |
| − | <pre class="brush:xml">
| + | |
| − | | + | |
| − | <service_requests>
| + | |
| − | | + | |
| − | <request>
| + | |
| − | <service_request_id>638344</service_request_id>
| + | |
| − | <token>12345</token>
| + | |
| − | </request>
| + | |
| − | | + | |
| − | </service_requests>
| + | |
| − | | + | |
| − | </pre>
| + | |
| − | | + | |
| − | ===GET Service Requests===
| + | |
| − | *'''Purpose:''' query the current status of a request
| + | |
| − | *'''URL:''' https://open311.sfgov.org/dev/v2/requests.[format]
| + | |
| − | *'''Sample URL:''' https://open311.sfgov.org/dev/v2/requests.xml?service_request_id=293450
| + | |
| − | *'''Formats: '''xml
| + | |
| − | *'''HTTP Method: '''GET
| + | |
| − | *'''Requires API Key: '''No
| + | |
| − | | + | |
| − | *'''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:'''
| + | |
| − | | + | |
| − | <pre class="brush:xml">
| + | |
| − | | + | |
| − | <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>
| + | |
| − | | + | |
| − | </pre>
| + | |
| − | | + | |
| − | ===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:'''
| + | |
| − | <pre class="brush:xml">
| + | |
| − | HTTP/1.1 401 Unauthorized
| + | |
| − | | + | |
| − | <error>Invalid api_key received -- can't proceed with create_request.</error>
| + | |
| − | </pre>
| + | |
