Revision as of 09:37, 30 April 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?api_key=xyz&jurisdiction_id=sfgov.org
• Formats: xml
• HTTP Method: GET
• Requires API Key: No
• Arguments:
  • jurisdiction_id (for SF = sfgov.org)
• Response:
  • name (was service_name)
  • code (was 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)

Example response:

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

• Arguments:
  • service_code

• Response:
  • variable
  • code
  • datatype (options: string, number, datetime, text, singlevaluelist, multivaluelist)
  • required (value is required to submit service request)
  • datatype_description
  • order
  • description
  • service_code
  • values (optional, provides list of values in comma separated format for singlevaluelist and multivaluelist)

Example response:

	<service_definition>
		<attribute>
			<variable>true</variable>
			<code>WHISHETN</code>
			<datatype>select_single</datatype>
			<required>true</required>
			<datatype_description></datatype_description>		
			<order>1</order>	
			<description>What is the ticket/tag/DL number?</description>
			<values>
			    <value key="123" name="label" />
				<value key="123" name="label" />
			</values>
		<attribute>	
		<service_code>DMV66</service_code>
	</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?api_key=xyz&jurisdiction_id=sfgov.org&service_code=001&lat=37.76524078&long=-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
• HTTP Method: POST
• Requires API Key: Yes
• Required Arguments:
  • api_key
  • 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 jpeg image)
  • source_url (URL of original report, eg from SeeClickFix - http://www.seeclickfix.com/issues/8060)

• 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)
  • error codes

About Responses There are three response types: realtime, asynchronous, and other. A realtime response will return a service_request_id, an asynchronous response will return a token, and if neither is returned an explanation will be provided in the service_notice field.

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

• 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&api_key=xxxx
• Formats: xml
• HTTP Method: GET
• Requires API Key: No

• 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

• 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:
  • none

• Optional Arguments:
  • service_request_id
  • service_code (can be declared multiple times)
  • start_date & end_date (should not span more than 90 days) (w3 format)
  • status (open, closed, rejected, etc)

• • lat,long (requires radius, if not available, returns error)
  • radius (if not available, returns error)

• Response:
  • service_request_id
  • status (open, closed, rejected (DC internally has open overdue and closed overdue statuses))
  • status_notes
  • service_name
  • service_code
  • description (not all cities return descriptions)
  • agency_responsible (not all cities return agency responsible)
  • service_notice
  • 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
  • geo:lat
  • geo:long
  • georss:point

Example response:

<service_requests>

	<request>
		<service_request_id>638344</service_request_id>
		<status>open</status>
		<status_notes/>
		<service_name>Sidewalk and Curb Issues</service_name>
		<service_code>006</service_code>
		<description></description>
		<datetime_requested>2010-04-14T06:37:38-08:00</datetime_requested>
		<address>8TH AVE and JUDAH ST</address>
		<zipcode>94122</zipcode>
		<geo:lat xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#">37.762221815</geo:lat>
		<geo:long xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#">-122.4651145</geo:long>
		<georss:point xmlns:georss="http://www.georss.org/georss">37.762221815 -122.4651145</georss:point>
	</request>

</service_requests>

Errors

Response:

• 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

• /services:
  • 408 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)

• /requests
  • 412 Missing service Code
  • 417 Invalid Service Code
  • 408 General Service Error ( anything captured during create_request processing , Lagan WS is down , ....An error description will follow. Client will need to notify us)

• /requests/12345.[format]
  • 409 Id not valid or you are attempting to search for a service request you did not create
  • 408 General Service error ( anything captured during status_update processing. It will always have an error description ..Client will have to notify us)

Example:

HTTP/1.1 401 Unauthorized 

<error>Invalid api_key received -- can't proceed with create_request.</error>