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:
- api_key
- jurisdiction_id (for SF = sfgov.org)
Response:
- service_name
- service_code
- service_description
- metadata (true = need to make service_defintion call, false = do not make service_definition call)

Example response:


<services>
		<service service_code="001" metadata="true" keywords="lorem, ipsum, dolor" group="sanitation" 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. "/>
		<service service_code="002" metadata="true" keywords="lorem, ipsum, dolor" group="street" service_name="Construction plate shifted" service_description="Metal construction plate covering the street or sidewalk has been moved. "/>
		<service service_code="003" metadata="true" keywords="lorem, ipsum, dolor" group="street" 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. "/>
		<service service_code="004" metadata="true" keywords="lorem, ipsum, dolor" group="sanitation" service_name="Damaged city can" service_description="Damage to a city garbage receptacle such as missing parts (lid, door, liner) or other physical damage. "/>
		<service service_code="005" metadata="true" keywords="lorem, ipsum, dolor" group="sewer" 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 service_code="006" metadata="true" keywords="lorem, ipsum, dolor" group="tree" service_name="Damaged tree" service_description="Damage to a city maintained tree. To check whether a tree is city maintained: http://bit.ly/6hsDk1"/>
		<service service_code="007" metadata="true" keywords="lorem, ipsum, dolor" group="graffiti" 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_code="008" metadata="true" keywords="lorem, ipsum, dolor" group="graffiti" 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_code="009" metadata="true" keywords="lorem, ipsum, dolor" group="graffiti" 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 service_code="010" metadata="true" keywords="lorem, ipsum, dolor" group="graffiti" 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.  "/>
		<service service_code="011" metadata="true" keywords="lorem, ipsum, dolor" group="graffiti" 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  "/>
		<service service_code="012" metadata="true" keywords="lorem, ipsum, dolor" group="graffiti" 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 "/>
		<service service_code="013" metadata="true" keywords="lorem, ipsum, dolor" group="graffiti" 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 "/>
		<service service_code="014" metadata="true" keywords="lorem, ipsum, dolor" group="graffiti" 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 service_code="015" metadata="true" keywords="lorem, ipsum, dolor" group="sanitation" 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 "/>
		<service service_code="016" metadata="true" keywords="lorem, ipsum, dolor" group="landscaping" 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_code="017" metadata="true" keywords="lorem, ipsum, dolor" group="street" 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_code="018" metadata="true" keywords="lorem, ipsum, dolor" group="sewer" 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 service_code="019" metadata="true" keywords="lorem, ipsum, dolor" group="sanitation" service_name="Overflowing city receptacle or dumpster" service_description="City receptacle is overflowing and/or has garbage on and around the container "/>
		<service service_code="020" metadata="true" keywords="lorem, ipsum, dolor" group="tree" 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 "/>
		<service service_code="021" metadata="true" keywords="lorem, ipsum, dolor" group="street" service_name="Pothole in Street" service_description="Defect on the street such as broken, cracked, and sinking asphalt or concrete "/>
		<service service_code="022" metadata="true" keywords="lorem, ipsum, dolor" group="sewer" 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) "/>
		<service service_code="023" metadata="true" keywords="lorem, ipsum, dolor" group="sewer" 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 service_code="024" metadata="true" keywords="lorem, ipsum, dolor" group="sidewalk" 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 "/>
		<service service_code="025" metadata="true" keywords="lorem, ipsum, dolor" group="sidewalk" service_name="Sidewalk defect" service_description="Defect on the sidewalk such as broken, cracked, and/or sinking concrete "/>
		<service service_code="026" metadata="true" keywords="lorem, ipsum, dolor" group=street"" service_name="Street cleaning" service_description="Request to have garbage or human waste removed from the street "/>
		<service service_code="027" metadata="true" keywords="lorem, ipsum, dolor" group="tree" 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 service_code="028" metadata="true" keywords="lorem, ipsum, dolor" group="water main" service_name="Water main break" service_description="Street is flooding due to water coming from within the asphalt or from a catchbasin "/>
		<service service_code="029" metadata="true" keywords="lorem, ipsum, dolor" group="graffiti" 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 "/>
		<service service_code="030" metadata="true" keywords="lorem, ipsum, dolor" group="sewer" 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.  "/>
		<service service_code="031" metadata="true" keywords="lorem, ipsum, dolor" group="sewer" 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) "/>
		<service service_code="032" metadata="true" keywords="lorem, ipsum, dolor" group="sewer" 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 service_code="033" metadata="true" keywords="lorem, ipsum, dolor" group="street" service_name="Pothole in bike lane" service_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:
- api_key
- service_code

Response:
- variable
- code
- datatype
- required
- datatype_description
- order
- description
- service_code
- values

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&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
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)
- lon (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 (optional)
- 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)

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

Required Arguments:
- jurisdiction_id
- token
- api_key

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)
- radius (if not available, returns error)

Response:
- service_request_id
- status
- status_notes
- service_name
- service_code
- description (not all cities return descriptions)
- agency_responsible
- service_notice
- service_notice_datetime
- datetime_requested (w3 format)
- updated_datetime
- address
- address_id
- 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>

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

Errors

Search

Tools

Navigation

Meta

Open311