Open311

Wiki

Collaboration for an Open311 Standard
Personal tools

GeoReport v3 Draft

Collaboration for an Open311 Standard

Revision as of 13:12, 21 April 2010 by Phil.ashlock.us (Talk | contribs)

Jump to: navigation, search

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

  • 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

  • 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

  • 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

  • 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

  • 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
Retrieved from "https://wiki-archive.open311.org/index.php?title=GeoReport_v3_Draft&oldid=448"