Open311

Wiki

Collaboration for an Open311 Standard
Personal tools

Difference between revisions of "GeoReport v3 Draft"

Collaboration for an Open311 Standard

Jump to: navigation, search
m (moved GeoReport v4 Draft to GeoReport v3 Draft: the previous v3 draft was renamed v2.5 because it was transitional. v4 is being moved to v3 because it represents a full new revision up from v2 (whereas the previous v3 draft did not))
(→‎GeoReport API)
 
Line 1: Line 1:
 
=GeoReport API=
 
=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 an extension of Atom (specifically [http://georss.org/ GeoRSS]) and uses the [http://www.ibm.com/developerworks/library/x-atompp1/ Atom Publishing Protocol] (aka [http://bitworking.org/projects/atom/rfc5023.html Atompub]) while accommodating JSON equivalents. The specification is generally influenced by characteristics of the [http://core.geocommons.com/help/GeoCommons_API GeoCommons API], [http://code.google.com/apis/gdata/docs/2.0/reference.html GData] (specifically the [http://code.google.com/apis/maps/documentation/mapsdata/developers_guide_protocol.html Google Maps Data API]), [http://www.odata.org/developers/protocols/atom-format oData], and even qualities of the [http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses%C2%A0update Twitter 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 an extension of Atom (specifically [http://georss.org/ GeoRSS]) and uses the [http://www.ibm.com/developerworks/library/x-atompp1/ Atom Publishing Protocol] (aka [http://bitworking.org/projects/atom/rfc5023.html Atompub]) while accommodating JSON equivalents. The specification is generally influenced by characteristics of the [http://core.geocommons.com/help/GeoCommons_API GeoCommons API], [http://code.google.com/apis/gdata/docs/2.0/reference.html GData] (specifically the [http://code.google.com/apis/maps/documentation/mapsdata/developers_guide_protocol.html Google Maps Data API]), [http://www.odata.org/developers/protocols/atom-format oData], and even qualities of the [http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses%C2%A0update Twitter API].  
 +
 +
'''Note:''' It might be worth looking into http://code.google.com/p/georest/ as well.
  
 
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''.
 
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''.

Latest revision as of 15:14, 3 August 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 an extension of Atom (specifically GeoRSS) and uses the Atom Publishing Protocol (aka Atompub) while accommodating JSON equivalents. The specification is generally influenced by characteristics of the GeoCommons API, GData (specifically the Google Maps Data API), oData, and even qualities of the Twitter API. 

Note: It might be worth looking into http://code.google.com/p/georest/ as well.

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

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.

JSON or XML

The core schema for a report is based on an Atom entry and extended with GeoRSS much like the Google Maps Data API extends Atom entries with KML markup. To provide this same schema in JSON, the XML can be translated to JSON using a 1:1 mapping convention like Badgerfish. The disadvantage of this is that the JSON generated is not as lean or flexible as it might be if generated independently. Another reason why this may be less desirable is that common JSON representations of geospatial features do not follow the same schema as GeoRSS XML, the common convention in JSON is GeoJSON. That said, there are many advantages to following a 1:1 mapping. Following a strict convention would make it much easier for service providers and clients to offer either format.

For examples of JSON and XML representations see: JSON and XML Conversion


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

<?xml version="1.0" encoding="utf-8"?>
<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>
			<attribute id="5887">There's a 2 inch deep pothole here</attribute>
			<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>
		<attribute id="5887">There's a 2 inch deep pothole here</attribute>
		<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

<?xml version="1.0" encoding="utf-8"?>
<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" 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/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" encoding="utf-8"?>
<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=617"