Revision as of 13:12, 21 April 2010

GeoReport API

The GeoReport API allows developers to build applications to submit geospatial reports such as a fallen tree, a broken street light, or a pothole directly to government organizations like cities. The specification is influenced by characteristics of the Atom Publishing Protocol, GData (specifically the Google Maps Data API), oData, GeoRSS, and the Twitter API.

The current draft has mostly been developed around input and output using the Atom XML format, but this will soon be expanded with the JSON alternatives. In most cases input should also be available using multipart/form-data and application/x-www-form-urlencoded.

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

Methods

Category Listing GET

Purpose: provide a list of acceptable report categories and associated parameters
URL:https://open311.sfgov.org/dev/V1/categories.[format]
Sample URL: https://open311.sfgov.org/dev/V1/categories.xml
Response Formats Supported: xml
HTTP Method: GET
Requires Authentication: false

Required Arguments: (If the API only serves one jurisdiction then lat and lon can be ignored)
- lat (WGS84)
- lon (WGS84)

Optional Arguments:
- jurisdiction_id
- accept_language - or Accept-Language specified in HTTP header

Example:

Request:

GET /dev/V1/categories.xml?lat=37.76524078&lon=-122.4212043

Response:

HTTP/1.1 200 OK 
Date: Thu, 15 Apr 2010 17:17:11 GMT
Content-Type: application/atom+xml; charset=utf-8
Content-Length: nnn
Content-Language: en-us
ETag: "/dev/V1/categories.xml"
Last-Modified: Sat, 15 Apr 2010 13:40:03 GMT


<categories>
		<category>
			<link rel="self" href="https://open311.sfgov.org/dev/V1/categories/033.xml" />
			<category_id>033</category_id>
			<category_label>Pothole in bike lane</category_label>
		 	<category_description>Defect in the bike lane such as broken, cracked, and sinking asphalt or concrete.<category_description/>
		
			<attribute>
				<link rel="self" href="https://open311.sfgov.org/dev/V1/categories/033/attributes/5887.xml" />			
				<attribute_id>5887</attribute_id>
				<attribute_label>Describe the defect</attribute_label>				
				<required>true</required>			
				<variable>true</variable>
				<active>true</active>
				<datatype>CHAR</datatype>
				<datatype_label>Character</datatype_label>
				<order>1</order>
			</attribute>
			
		</category>

</categories>

Create Report POST

Purpose: Create a new report
URL: https://open311.sfgov.org/dev/V1/reports.[format]
Sample URL:https://open311.sfgov.org/dev/V1/reports.xml
Response Formats Supported: xml
Accepts: application/atom+xml, multipart/form-data, application/x-www-form-urlencoded
HTTP Method: POST
Requires Authentication: true (using Basic Auth)

Required Arguments:
- category (obtained from method category_list)
- 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 (human entered description of location)(if no lat/lon must provide this information)

Optional Arguments:
- jurisdiction_id
- email
- device_id
- account_id
- name (given name)
- surname (family name)
- phone_number
- description (free form text)
- link (uri for associated media)
- accept_language - or Accept-Language specified in HTTP header

HTTP response code:
- 201 Created (on success)

Example:

Request: (using application/atom+xml):

POST /dev/V1/reports
Host: open311.sfgov.org
Content-Length: nnn
Content-Type: application/atom+xml; charset=utf-8
Accept-Language: en-us, en-gb;q=0.9, en;q=0.8
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==


<?xml version="1.0"  encoding='utf-8'?>
<entry xmlns="http://www.w3.org/2005/Atom" 
	   xmlns:georss="http://www.georss.org/georss">
		
		<id>null</id>
		<title>null</title>
		<updated>2010-01-01T12:00:00Z</updated>
		<author><name>John Doe</name></author>

	   	<georss:point>45.256 -71.92</georss:point>
		
		<category label="Pothole in bike lane" term="pothole" scheme="https://open311.sfgov.org/dev/V1/categories/033.xml">033</category>

		<content type="xml" xmlns="http://open311.org/spec/georeport-v1">
		
			<reporter>
				<name>John</name>
				<surname>Doe</surname>
				<account_id>56464684654</account_id>	
				<device_id>987987897</device_id>
				<phone_number>1.415.555.1212</phone_number>
				<email>john@doe.com</email>
			</reporter>
		
			<jurisdiction_id>http://sfgov.org</jurisdiction_id>
			<address>1600 Market St, San Francisco, CA 94103</address>
			<description>There's a 2 inch deep pothole here</description>
			<link rel="media" type="image/jpeg" href="http://farm3.static.flickr.com/2589/3975416561_ba69ddcae9_b.jpg" />
			
		</content>
		
</entry>

Response:

HTTP/1.1 201 Created
Date: Thu, 15 Apr 2010 17:17:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml; charset=utf-8
Content-Language: en-us
Content-Location: https://open311.sfgov.org/dev/V1/reports/637618.xml
Location: https://open311.sfgov.org/dev/V1/reports/637618.xml

<?xml version="1.0"  encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" 
	   xmlns:georss="http://www.georss.org/georss">

	<id>tag:open311.sfgov.org,2010-04-15:/dev/V1/reports/637618.xml</id>	
	<title>Pothole in bike lane</title>
	<updated>2010-04-15T18:30:02-05:00</updated>
	<link rel="self" href="http://open311.sfgov.org/dev/V1/reports/637618.xml"/>	
	<author><name>John Doe</name></author>

	<georss:point>40.7111 -73.9565</georss:point>

	<category label="Pothole in bike lane" term="graffiti" scheme="https://open311.sfgov.org/dev/V1/categories/033.xml">033</category>

	<content type="xml" xmlns="http://open311.org/spec/georeport-v1">
	
		<reporter>
			<name>John</name>
			<surname>Doe</surname>
		</reporter>		
	
		<report_id>637618</report_id>
		<jurisdiction_id>http://sfgov.org</jurisdiction_id>
		<address>1600 Market St, San Francisco, CA 94103</address>
		<description>There's a 2 inch deep pothole here</description>
		<link rel="media" type="image/jpeg" href="http://farm3.static.flickr.com/2589/3975416561_ba69ddcae9_b.jpg" />
		<status>created</status>
		<status_notes />
		<policy>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</policy>
	</content>
	
</entry>

Report Feed GET

Purpose: list reports
URL: https://open311.sfgov.org/dev/V1/reports.[format]
Sample URL: https://open311.sfgov.org/dev/V1/reports.xml?start_date=2010-04-13&end_date=2010-04-14
Response Formats Supported: xml
HTTP Method: GET
Requires Authentication: false

Required Arguments:
- none

Optional Arguments:
- category_id
- start_date (eg 2010-04-14)
- end_date (eg 2010-04-14)
- accept_language - or Accept-Language specified in HTTP header

HTTP Response codes:
- 200 OK
- 404 Not Found

Example:

Request:

GET /dev/V1/reports.xml?start_date=2010-04-13&end_date=2010-04-14&category_id=006

Response:

HTTP/1.1 200 OK 
Date: Thu, 15 Apr 2010 17:17:11 GMT
Content-Type: application/atom+xml; charset=utf-8
Content-Length: nnn
Content-Language: en-us
ETag: "/dev/V1/reports.xml"
Last-Modified: Sat, 15 Apr 2010 13:40:03 GMT

<reports xmlns="http://www.w3.org/2005/Atom" 
	   xmlns:georss="http://www.georss.org/georss">
	
	<entry>
		<id>tag:open311.sfgov.org,2010-04-15:/dev/V1/reports/637619.xml</id>	
		<title>A large tree branch is blocking the road</title>
		<updated>2010-04-13T18:30:02-05:00</updated>
		<link rel="self" href="http://open311.sfgov.org/dev/V1/reports/637619.xml"/>	
		<author><name>John Doe</name></author>	
				
		<georss:point>40.7111 -73.9565</georss:point>

		<category label="Damaged tree" term="tree-damage" scheme="https://open311.sfgov.org/dev/V1/categories/006.xml">006</category>

		<content type="xml" xmlns="http://open311.org/spec/georeport-v1">
			<report_id>637619</report_id>
			<address>1600 Market St, San Francisco, CA 94103</address>
			<description>A large tree branch is blocking the road</description>
			<status>created</status>
			<status_notes />
			<policy>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</policy>		
		</content>
	
	</entry>

	<entry>
		<id>tag:open311.sfgov.org,2010-04-15:/dev/V1/reports/637620.xml</id>	
		<title>A large tree branch is blocking the road</title>
		<updated>2010-04-13T18:30:02-05:00</updated>
		<link rel="self" href="http://open311.sfgov.org/dev/V1/reports/637620.xml"/>	
		<author><name>John Doe</name></author>
				
		<georss:point>40.7111 -73.9565</georss:point>

		<category label="Damaged tree" term="tree-damage" scheme="https://open311.sfgov.org/dev/V1/categories/006.xml">006</category>

		<content type="xml" xmlns="http://open311.org/spec/georeport-v1">
			<report_id>637620</report_id>
			<address>56 Market St, San Francisco, CA 94103</address>
			<description>A large tree branch is blocking the road</description>
			<status>created</status>
			<status_notes />
			<policy>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</policy>
		</content>
	
	</entry>

	<entry>
		<id>tag:open311.sfgov.org,2010-04-15:/dev/V1/reports/637621.xml</id>	
		<title>A large tree branch is blocking the road</title>
		<updated>2010-04-13T18:30:02-05:00</updated>
		<link rel="self" href="http://open311.sfgov.org/dev/V1/reports/637621.xml"/>	
		<author><name>John Doe</name></author>
		
		<georss:point>40.7111 -73.9565</georss:point>

		<category label="Damaged tree" term="tree-damage" scheme="https://open311.sfgov.org/dev/V1/categories/006.xml">006</category>

		<content type="xml" xmlns="http://open311.org/spec/georeport-v1">
			<report_id>637621</report_id>
			<address>1800 Market St, San Francisco, CA 94103</address>
			<description>A large tree branch is blocking the road</description>
			<status>created</status>
			<status_notes />
			<policy>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</policy>
		</content>
	
	</entry>
	
</reports>

Report GET

Purpose: query a specific report
URL: https://open311.sfgov.org/dev/V1/reports/[report_id].[format]
Sample URL: https://open311.sfgov.org/dev/V1/reports/637621.xml
Response Formats Supported: xml
HTTP Method: GET
Requires Authentication: false

Required Arguments:
- none

Optional Arguments:
- accept_language - or Accept-Language specified in HTTP header

HTTP Response codes:
- 200 OK
- 404 Not Found

Example:

Request:

GET /dev/V1/reports/637621.xml

Response:

HTTP/1.1 200 OK 
Date: Thu, 15 Apr 2010 17:17:11 GMT
Content-Type: application/atom+xml; charset=utf-8
Content-Length: nnn
Content-Language: en-us
ETag: "/dev/V1/reports/637618.xml"
Last-Modified: Sat, 15 Apr 2010 13:40:03 GMT

<?xml version="1.0" ?>
<entry xmlns="http://www.w3.org/2005/Atom" 
	   xmlns:georss="http://www.georss.org/georss">
	
	<id>tag:open311.sfgov.org,2010-04-15:/dev/V1/reports/637621.xml</id>	
	<title>A large tree branch is blocking the road</title>
	<updated>2010-04-13T18:30:02-05:00</updated>
	<link rel="self" href="http://open311.sfgov.org/dev/V1/reports/637621.xml"/>	
	<author><name>John Doe</name></author>
	
	<georss:point>40.7111 -73.9565</georss:point>

	<category label="Damaged tree" term="tree-damage" scheme="https://open311.sfgov.org/dev/V1/categories/006.xml">006</category>

	<content type="xml" xmlns="http://open311.org/spec/georeport-v1">
		<report_id>637621</report_id>
		<address>1800 Market St, San Francisco, CA 94103</address>
		<description>A large tree branch is blocking the road</description>
		<status>created</status>
		<status_notes />
		<policy>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</policy>
	</content>

</entry>

Report PUT

Purpose: update status of a report
URL: https://open311.sfgov.org/dev/V1/reports/[id].[format]
Sample URL: https://open311.sfgov.org/dev/V1/reports/637618.xml
Response Formats Supported: xml
Accepts: application/atom+xml, multipart/form-data, application/x-www-form-urlencoded
Requires Authentication: true (using Basic Auth)
HTTP Method: PUT

Required arguments:
- none

Optional arguments: (data you can update)
- status
- status_notes
- accept_language - or Accept-Language specified in HTTP header

HTTP response codes:
- 200 OK
- 404 Not found
- 401 Unauthorized
- 400 Bad Request

Example:

Request:

PUT /dev/V1/reports/637618.xml
Host: https://open311.sfgov.org
Content-Type: application/atom+xml; charset=utf-8
Accept-Language: en-us, en-gb;q=0.9, en;q=0.8
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<?xml version="1.0" ?>
<entry xmlns="http://www.w3.org/2005/Atom" >

	<content type="xml" xmlns="http://open311.org/spec/georeport-v1">
		<status>closed</status>
		<status_notes>We have cleaned this up</status_notes>
	</content>
	
</entry>

Response:

HTTP/1.1 200 OK 
Date: Thu, 15 Apr 2010 17:17:11 GMT
Content-Type: application/atom+xml; charset=utf-8
Content-Length: nnn
Content-Language: en-us
ETag: "/dev/V1/reports/637618.xml"
Last-Modified: Sat, 15 Apr 2010 13:40:03 GMT
Content-Location: https://open311.sfgov.org/dev/V1/reports/637618.xml
Location: https://open311.sfgov.org/dev/V1/reports/637618.xml

Open311

Wiki

Personal tools

Views

Difference between revisions of "GeoReport v3 Draft"

Collaboration for an Open311 Standard

Revision as of 13:12, 21 April 2010

Contents

GeoReport API

Internationalization and Encoding

Definitions

jurisdiction_id

Methods

Category Listing GET

Create Report POST

Report Feed GET

Report GET

Report PUT

Search

Tools

Navigation

Meta

Open311