Revision as of 09:26, 24 June 2010

For the stable v2 spec, see GeoReport v2

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 root element must be preceded with the XML declaration including the 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

• Required 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)
  • 412 - jurisdiction_id was not provided (specify in error response)
  • 404 - jurisdiction_id provided was not found (specify in error response)
  • 400 - General service error (Anything that fails during service list processing. The client will need to notify us)

Example response:

<?xml version="1.0" encoding="utf-8"?>
<services>
	<service>
		<service_code>001</service_code>
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sanitation</group>
		<service_name>Cans left out 24x7</service_name>
		<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_name>Construction plate shifted</service_name>
		<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_name>Curb or curb ramp defect</service_name>
		<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_name>Damaged city can</service_name>
		<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_name>Damaged side sewer vent cover</service_name>
		<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_name>Damaged tree</service_name>
		<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_name>Graffiti on bike rack - not offensive</service_name>
		<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_name>Graffiti on news rack - not offensive</service_name>
		<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_name>Graffiti on parking meter - not offensive</service_name>
		<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_name>Graffiti on pay phone - not offensive</service_name>
		<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_name>Graffiti on private property - not offensive</service_name>
		<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_name>Graffiti on private property - offensive</service_name>
		<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_name>Graffiti on public property - offensive</service_name>
		<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_name>Graffiti on public property- not offensive</service_name>
		<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_name>Illegal dumping</service_name>
		<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_name>Landscaping request</service_name>
		<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_name>Missed route - mechanical sweeping</service_name>
		<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_name>Missing side sewer vent cover</service_name>
		<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_name>Overflowing city receptacle or dumpster</service_name>
		<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_name>Overgrown tree</service_name>
		<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_name>Pothole in Street</service_name>
		<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_name>Sewage coming out of catch basin</service_name>
		<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_name>Water coming from side sewer</service_name>
		<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_name>Sidewalk cleaning</service_name>
		<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_name>Sidewalk defect</service_name>
		<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_name>Street cleaning</service_name>
		<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_name>Tree damaging property</service_name>
		<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_name>Water main break</service_name>
		<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_name>Graffiti on street sign</service_name>
		<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_name>Odor coming from Side Sewer</service_name>
		<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_name>Sewage coming out of manhole cover</service_name>
		<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_name>Sewage coming out of sewer vent</service_name>
		<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_name>Pothole in bike lane</service_name>
		<description>Defect in the bike lane such as broken, cracked, and sinking asphalt or concrete.</description>
	</service>
</services>

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

• Required 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

• Possible Errors (with HTTP status codes)
  • 412 - service_code or jurisdiction_id was not provided (specify in error response)
  • 404 - service_code or jurisdiction_id provided were not found (specify in error response)
  • 400 - General service error (Anything that fails during service list processing. The client will need to notify us)

Example response:

<?xml version="1.0" encoding="utf-8"?>
<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

• Purpose: Create service requests
• URL: https://open311.sfgov.org/dev/v2/requests.[format]
• Sample URL:https://open311.sfgov.org/dev/v2/requests.xml
• Format sent: Content-Type: application/x-www-form-urlencoded
• Formats returned: xml
• HTTP Method: POST
• Requires API Key: Yes

• Required Arguments:
  • jurisdiction_id
  • service_code (obtained from method service_list)

• Optional Arguments:
  • lat (WGS84) (required - either lat/lon or address string, both are preferred)
  • long (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)
  • 404 - service_code or jurisdiction_id was not found (specified in error response)
  • 412 - service_code or jurisdiction_id was not provided (specified in error response)
  • 400 - General Service Error (Any failure during create request processing, eg CRM is down. Client will need to notify us)

Example request:

POST /dev/v2/requests.xml
Host: open311.sfgov.org
Content-Type: application/x-www-form-urlencoded; charset=utf-8

api_key=xyz&jurisdiction_id=sfgov.org&service_code=001&lat=37.76524078&long=-122.4212043&address_string=1234+5th+street&email=smit333%40sfgov.edu&device_id=tt222111&account_id=123456&first_name=john&last_name=smith&phone=111111111&description=A+large+sinkhole+is+destroying+the+street&media_url=http%3A%2F%2Ffarm3.static.flickr.com%2F2002%2F2212426634_5ed477a060.jpg

Example response:

<?xml version="1.0" encoding="utf-8"?>
<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

• Purpose: get the request_id from a temporary token. This is unnecessary if the response from creating a service request does not contain a 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

• Possible Errors (with HTTP status codes)
  • 404 - jurisdiction_id or token not found (specified in error response)
  • 412 - jurisdiction_id or token was not provided (specified in error response)
  • 400 - General Service error (Any failure during service query processing. Client will have to notify us)

Example response:

<?xml version="1.0" encoding="utf-8"?>
<service_requests>
	<request>
		<service_request_id>638344</service_request_id>
		<token>12345</token>
	</request>
</service_requests>

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)
  • 404 - jurisdiction_id not found (specified in error response)
  • 412 - jurisdiction_id was not provided (specified in error response)
  • 400 - General Service error (Any failure during service query processing. Client will have to notify us)

Example response:

<?xml version="1.0" encoding="utf-8"?>
<service_requests>
<request>
	<service_request_id>638344</service_request_id>
	<status>closed</status>
	<status_notes>Duplicate request.</status_notes>
	<service_name>Sidewalk and Curb Issues</service_name>
	<service_code>006</service_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>

Errors

Response:

• status code - returned in HTTP header as HTTP status code
• error (description of error)

• General Errors
  • 401 - Missing or Invalid API Key (specify in error message)
  • 400 - 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 

<?xml version="1.0" encoding="utf-8"?>
<error>Invalid api_key received -- can't proceed with create_request.</error>