Difference between revisions of "GeoReport v2 Draft"

Revision as of 16:04, 6 May 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 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:

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

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:

<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?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 (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
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:
- 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:


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

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>

Revision as of 15:01, 6 May 2010 (view source) Phil.ashlock.us (Talk \| contribs) (Rolling v2.1 drafting page back into main v2 space. Changes documented at http://wiki.open311.org/Talk:GeoReport_v2.1_Draft) ← Older edit		Revision as of 16:04, 6 May 2010 (view source) Philipashlock (Talk \| contribs) Newer edit →
Line 1:		Line 1:
		+	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.		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.

Open311

Wiki

Personal tools

Views

Difference between revisions of "GeoReport v2 Draft"

Collaboration for an Open311 Standard

Revision as of 16:04, 6 May 2010

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