GeoReport v2.1 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 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)

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:

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


<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 (can be declared multiple times; overrides all other arguments)
- service_code (defaults to all service codes; can be declared multiple times)
- start_date & end_date (defaults to most recent 90 days; should not span more than 90 days) (w3 format)
- status (defaults to all statuses; options are: open, closed)

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

Response:
- service_request_id
- status (open, closed)
- status_notes (may not be returned; optional explanation of why status was changed)
- name (was service_name)
- code (was service_code)
- description (not all cities return descriptions)
- agency_responsible (not all cities return agency responsible)
- service_notice (was service_level_agreement)
- 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

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

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>

Open311

Wiki

Personal tools

Views

GeoReport v2.1 Draft

Collaboration for an Open311 Standard

Contents

Internationalization and Encoding

Date/time format

Encoding

Definitions

jurisdiction_id

API methods

GET Service List

GET Service Definition

POST Service Request

GET token with request_id

GET Service Requests

General Errors

Search

Tools

Navigation

Meta

Open311