Open311

Wiki

Collaboration for an Open311 Standard
Personal tools

Difference between revisions of "GeoReport v2 Draft"

Collaboration for an Open311 Standard

Jump to: navigation, search
(clarified that values would be predefined and included in the response)
(updated formatting and clarified definitions for POST Service Requests)
Line 487: Line 487:
 
*'''Requires API Key:''' Yes
 
*'''Requires API Key:''' Yes
  
−
*'''Required Arguments:'''
+
====Required Arguments====
−
** jurisdiction_id
+
* '''jurisdiction_id'''
−
** service_code (obtained from method service_list)
+
* '''service_code''' (obtained from [[#GET_Service_List|GET Service List]] method)
 +
* location: either '''lat''' & '''long''' or '''address_string''' must be submitted
  
−
*'''Optional Arguments:'''
+
====Optional Arguments====
−
** lat [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] (required - either lat/lon or address string, both are preferred)
+
* '''lat'''  
−
** long [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] (required - either lat/lon or address string, both are preferred)
+
**Explanation: latitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
−
** address_string (human entered description of location)(if no lat/lon must provide this information)
+
* '''long''' [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)]  
−
** address_id - ID in Master Address Repository
+
**Explanation: longitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
−
** email
+
* '''address_string'''
−
** device_id  
+
**Explanation: Human entered address or description of location. This should be written from most specific to most general geographic unit, eg address number or cross streets, street name, neighborhood/district, city/town/village, county, postal code. This is required if no lat/lon is provided.
−
** account_id
+
* '''address_id'''
−
** first_name
+
**Explanation: The internal address ID used by a jurisdictions master address repository or other addressing system.
−
** last_name  
+
* '''email'''
−
** phone
+
**Explanation: The email address of the person submitting the request
−
** description (free form limited to 4,000 characters)
+
* '''device_id'''
−
** media_url (URL to [http://video.search.yahoo.com/mrss media RSS] feed of media associated with the request, eg an image)
+
**Explanation: The unique device ID of the device submitting the request. This is usually only used for mobile devices. For example, Android devices use TelephonyManager.getDeviceId() and iPhone's use [UIDevice currentDevice].uniqueIdentifier
−
** attribute (an array of key/value responses based on Service Definitions. This takes the form of attribute[code]=value where multiple code/value pairs can be specified - see example)
+
* '''account_id'''
 +
**Explanation: The unique ID for the user account of the person submitting the request
 +
* '''first_name'''
 +
**Explanation: The given name of the person submitting the request
 +
* '''last_name'''
 +
**Explanation: The family name of the person submitting the request
 +
* '''phone'''
 +
**Explanation: The phone number of the person submitting the request
 +
* '''description'''
 +
**Explanation: A full description of the request or report being submitted. This may contain line breaks, but not html or code. Otherwise, this is free form text limited to 4,000 characters.
 +
* '''media_url'''
 +
**Explanation: A URL to [http://video.search.yahoo.com/mrss media RSS] feed of media associated with the request, eg an image)
 +
* '''attribute'''
 +
**Explanation: An array of key/value responses based on Service Definitions. This takes the form of attribute[code]=value where multiple code/value pairs can be specified - see example
  
−
*'''Response: '''
+
====Response====
−
** service_request_id (may not be returned if token is returned)
+
*'''service_requests'''
−
** token (if returned then use token method)
+
**Explanation: root element
−
** service_notice (may not be returned)
+
*'''request'''
−
** account_id (may not be returned)
+
**Parent: service_requests
 +
**Explanation: container for service_request_id, token, service_notice, account_id
 +
*'''service_request_id'''
 +
**Parent: request
 +
**Explanation: The unique ID of the service request created. This will not be returned if token is returned
 +
*'''token'''
 +
**Parent: request
 +
**Explanation: If returned, use this to call [[#GET_request_id_from_a_token|GET request_id from a token]] This will not be returned if service_request_id is returned
 +
*'''service_notice'''
 +
**Parent: request
 +
**Explanation: Information about the action expected to fulfill the request or otherwise address the information reported. (may not be returned)
 +
*'''account_id'''
 +
**Parent: request
 +
**Explanation:  The unique ID for the user account of the person submitting the request. (may not be returned)
  
−
*  '''Possible Errors''' (with HTTP status codes)
+
====Possible Errors====
−
** 404 - service_code or jurisdiction_id was not found (specified in error response)
+
The numbers represent the HTTP status code returned for each error type:
−
** 400 - service_code or jurisdiction_id was not provided (specified in error response)
+
−
** 400 - General Service Error (Any failure during create request processing, eg CRM is down. Client will need to notify us)
+
  
−
'''Example request:'''
+
* 404 - service_code or jurisdiction_id was not found (specified in error response)
 +
* 400 - service_code or jurisdiction_id was not provided (specified in error response)
 +
* 400 - General Service Error (Any failure during create request processing, eg CRM is down. Client will need to notify us)
 +
 
 +
====Example Request====
 
<pre class="brush:xml">
 
<pre class="brush:xml">
 
POST /dev/v2/requests.xml
 
POST /dev/v2/requests.xml

Revision as of 17:39, 27 September 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 root element must be preceded with the XML declaration including the 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 distinguish multiple jurisdictions we've included a "jurisdiction_id" which will be the unique identifier for cities. It has been suggested that we use the jurisdiction's main website root url (without the www) as the "jurisdiction_id". For San Francisco, the jurisdiction_id is sfgov.org. Implementations can ignore this parameter and treat it as an "Optional Argument" if the implementation only serves one jurisdiction.

Optional Arguments

"Optional" means that the response should be the same whether a parameter is passed and is empty or is not passed at all. A null parameter should be treated as equivalent to a non-declared parameter in processing the request.

API methods

GET Service List

Required Arguments

  • jurisdiction_id

Response

  • services
    • Explanation: root element
  • service
    • Parent: services
    • Explanation: container for service_code, service_name, description, metadata, type, keywords, group
  • service_code
    • Parent: service
    • Explanation: The unique identifier for the service request type
  • service_name
    • Parent: service
    • Explanation: The human readable name of the service request type
  • description
    • Parent: service
    • Explanation: A brief description of the service request type.
  • metadata
    • Parent: service
    • Explanation: Possible values: true, false
      • true: This service request type requires additional metadata so the client will need to make a call to the Service Definition method
      • false: No additional information is required and a call to the Service Definition method is not needed.
  • type
    • Parent: service
    • Explanation: Possible values: realtime, batch, blackbox
      • realtime: The service request ID will be returned immediately after the service request is submitted
      • batch: A token will be returned immediately after the service request is submitted. This token can then be later used to return the service request ID.
      • blackbox: No service request ID will be returned after the service request is submitted
    • Explanation:
  • keywords
    • Parent: service
    • Explanation: A comma separated list of tags or keywords to help users identify the request type. This can provide synonyms of the service_name and group.
  • group
    • Parent: service
    • Explanation: A category to group this service type within. This provides a way to group several service request types under one category such as "sanitation"

Possible Errors

The numbers represent the HTTP status code returned for each error type:

  • 404 - jurisdiction_id provided was not found (specify in error response)
  • 400 - jurisdiction_id was not provided (specify in error response)
  • 400 - General service error (Anything that fails during service list processing. The client will need to notify us)

Example response

<?xml version="1.0" encoding="utf-8"?>
<services>
	<service>
		<service_code>001</service_code>
		<service_name>Cans left out 24x7</service_name>
		<description>Garbage or recycling cans that have been left out for more than 24 hours after collection. Violators will be cited.</description>
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>sanitation</group>
	</service>
	<service>
		<service_code>002</service_code>
		<metadata>true</metadata>
		<type>realtime</type>
		<keywords>lorem, ipsum, dolor</keywords>
		<group>street</group>
		<service_name>Construction plate shifted</service_name>
		<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_name>Curb or curb ramp defect</service_name>
		<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_name>Damaged city can</service_name>
		<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_name>Damaged side sewer vent cover</service_name>
		<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_name>Damaged tree</service_name>
		<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_name>Graffiti on bike rack - not offensive</service_name>
		<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_name>Graffiti on news rack - not offensive</service_name>
		<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_name>Graffiti on parking meter - not offensive</service_name>
		<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_name>Graffiti on pay phone - not offensive</service_name>
		<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_name>Graffiti on private property - not offensive</service_name>
		<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_name>Graffiti on private property - offensive</service_name>
		<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_name>Graffiti on public property - offensive</service_name>
		<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_name>Graffiti on public property- not offensive</service_name>
		<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_name>Illegal dumping</service_name>
		<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_name>Landscaping request</service_name>
		<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_name>Missed route - mechanical sweeping</service_name>
		<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_name>Missing side sewer vent cover</service_name>
		<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_name>Overflowing city receptacle or dumpster</service_name>
		<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_name>Overgrown tree</service_name>
		<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_name>Pothole in Street</service_name>
		<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_name>Sewage coming out of catch basin</service_name>
		<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_name>Water coming from side sewer</service_name>
		<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_name>Sidewalk cleaning</service_name>
		<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_name>Sidewalk defect</service_name>
		<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_name>Street cleaning</service_name>
		<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_name>Tree damaging property</service_name>
		<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_name>Water main break</service_name>
		<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_name>Graffiti on street sign</service_name>
		<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_name>Odor coming from Side Sewer</service_name>
		<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_name>Sewage coming out of manhole cover</service_name>
		<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_name>Sewage coming out of sewer vent</service_name>
		<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_name>Pothole in bike lane</service_name>
		<description>Defect in the bike lane such as broken, cracked, and sinking asphalt or concrete.</description>
	</service>
</services>

GET Service Definition

  • Conditional: Yes - This call is only necessary if the Service selected has metadata set as true from the GET Services response
  • Purpose: define attributes associated with a service code
  • URL: https://[API endpoint]/services/[service_code].[format]
  • Sample URL: https://open311.sfgov.org/dev/v2/services/033.xml?jurisdiction_id=sfgov.org
  • Formats: xml
  • HTTP Method: GET
  • Requires API Key: No

Required Arguments

  • service_code
  • jurisdiction_id (for SF = sfgov.org)

Response

  • service_definition
    • Explanation: root element
  • service_code
    • Parent: service_definition
    • Explanation: Returns the service_code associated with the definition, the same one submitted for this call.
  • attribute
    • Parent: service_definition
    • Explanation: container for the following elements:
  • variable
    • Parent: attribute
    • Options: true, false
    • Explanation: Setting true denotes that user input is needed, false means the attribute is only used to present information to the user within the description field
  • code
    • Parent: attribute
    • Explanation: A unique identifier for the attribute
  • datatype
    • Parent: attribute
    • Options: string, number, datetime, text, singlevaluelist, multivaluelist
      • string: A string of characters without line breaks. Represented in an HTML from using an <input> tag
      • number: A numeric value. Represented in an HTML from using an <input> tag
      • datetime: The input generated must be able to transform into a valid ISO 8601 date. Represented in an HTML from using <input> tags
      • text: A string of characters that may contain line breaks. Represented in an HTML from using an <textarea> tag
      • singlevaluelist: A set of predefined values (specified in this response) where only one value may be selected. Represented in an HTML from using the <select> and <option> tags
      • multivaluelist: A set of predefined values (specified in this response) where several values may be selected. Represented in an HTML from using the <select multiple="multiple"> and <option> tags
    • Explanation: Denotes the type of field used for user input.
  • required
    • Parent: attribute
    • Options: true, false
    • Explanation: Setting true means that the value is required to submit service request
  • datatype_description
    • Parent: attribute
    • Explanation: A description of the datatype which helps the user provide their input
  • order
    • Parent: attribute
    • Options: Any positive integer not used for other attributes in the same service_code
    • Explanation: The sort order that the attributes will be presented to the user. 1 is shown first
  • description
    • Parent: attribute
    • Explanation: An description of the attribute field with instructions for the user to find and identify the requested information
  • values
    • Parent: attribute
    • Explanation: Provides list of predefined values for singlevaluelist and multivaluelist. Required if datatype is set to singlevaluelist or multivaluelist.

Possible Errors

The numbers represent the HTTP status code returned for each error type:

  • 404 - service_code or jurisdiction_id provided were not found (specify in error response)
  • 400 - service_code or jurisdiction_id was not provided (specify in error response)
  • 400 - General service error (Anything that fails during service list processing. The client will need to notify us)

Example response

<?xml version="1.0" encoding="utf-8"?>
<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://[API endpoint]/requests.[format]
  • Sample URL: https://open311.sfgov.org/dev/v2/requests.xml
  • Format sent: Content-Type: application/x-www-form-urlencoded
  • Formats returned: xml
  • HTTP Method: POST
  • Requires API Key: Yes

Required Arguments

  • jurisdiction_id
  • service_code (obtained from GET Service List method)
  • location: either lat & long or address_string must be submitted

Optional Arguments

  • lat
    • Explanation: latitude using the (WGS84) projection.
  • long (WGS84)
    • Explanation: longitude using the (WGS84) projection.
  • address_string
    • Explanation: Human entered address or description of location. This should be written from most specific to most general geographic unit, eg address number or cross streets, street name, neighborhood/district, city/town/village, county, postal code. This is required if no lat/lon is provided.
  • address_id
    • Explanation: The internal address ID used by a jurisdictions master address repository or other addressing system.
  • email
    • Explanation: The email address of the person submitting the request
  • device_id
    • Explanation: The unique device ID of the device submitting the request. This is usually only used for mobile devices. For example, Android devices use TelephonyManager.getDeviceId() and iPhone's use [UIDevice currentDevice].uniqueIdentifier
  • account_id
    • Explanation: The unique ID for the user account of the person submitting the request
  • first_name
    • Explanation: The given name of the person submitting the request
  • last_name
    • Explanation: The family name of the person submitting the request
  • phone
    • Explanation: The phone number of the person submitting the request
  • description
    • Explanation: A full description of the request or report being submitted. This may contain line breaks, but not html or code. Otherwise, this is free form text limited to 4,000 characters.
  • media_url
    • Explanation: A URL to media RSS feed of media associated with the request, eg an image)
  • attribute
    • Explanation: An array of key/value responses based on Service Definitions. This takes the form of attribute[code]=value where multiple code/value pairs can be specified - see example

Response

  • service_requests
    • Explanation: root element
  • request
    • Parent: service_requests
    • Explanation: container for service_request_id, token, service_notice, account_id
  • service_request_id
    • Parent: request
    • Explanation: The unique ID of the service request created. This will not be returned if token is returned
  • token
    • Parent: request
    • Explanation: If returned, use this to call GET request_id from a token This will not be returned if service_request_id is returned
  • service_notice
    • Parent: request
    • Explanation: Information about the action expected to fulfill the request or otherwise address the information reported. (may not be returned)
  • account_id
    • Parent: request
    • Explanation: The unique ID for the user account of the person submitting the request. (may not be returned)

Possible Errors

The numbers represent the HTTP status code returned for each error type:

  • 404 - service_code or jurisdiction_id was not found (specified in error response)
  • 400 - service_code or jurisdiction_id was not provided (specified in error response)
  • 400 - General Service Error (Any failure during create request processing, eg CRM is down. Client will need to notify us)

Example Request

POST /dev/v2/requests.xml
Host: open311.sfgov.org
Content-Type: application/x-www-form-urlencoded; charset=utf-8

api_key=xyz&jurisdiction_id=sfgov.org&service_code=001&lat=37.76524078&long=-122.4212043&address_string=1234+5th+street&email=smit333%40sfgov.edu&device_id=tt222111&account_id=123456&first_name=john&last_name=smith&phone=111111111&description=A+large+sinkhole+is+destroying+the+street&media_url=http%3A%2F%2Ffarm3.static.flickr.com%2F2002%2F2212426634_5ed477a060.jpg&attribute[WHISPAWN]=123456&attribute[WHISDORN]=COISL001

Example response: 

<?xml version="1.0" encoding="utf-8"?>
<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 request_id from a token

  • Conditional: Yes - This call is only necessary if the response from POST Service Request contains a token
  • Purpose: get the request_id from a temporary token. This is unnecessary if the response from creating a service request does not contain a token.
  • URL: https://[API endpoint]/tokens/[token id].[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
  • Possible Errors (with HTTP status codes)
    • 404 - jurisdiction_id or token not found (specified in error response)
    • 400 - jurisdiction_id or token was not provided (specified in error response)
    • 400 - General Service error (Any failure during service query processing. Client will have to notify us)

Example response: 

<?xml version="1.0" encoding="utf-8"?>
<service_requests>
	<request>
		<service_request_id>638344</service_request_id>
		<token>12345</token>
	</request>
</service_requests>



GET Service Requests

  • 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 when not declared; can be declared multiple times, comma delimited)
    • start_date & end_date (search for requests with a requested_datetime that match a given range. defaults to most recent 90 days; should not span more than 90 days) (w3 format, eg 2010-01-01T00:00:00Z)
    • 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
    • media_url (URL to media RSS feed of media associated with the request, eg an image)
  • 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)
    • 404 - jurisdiction_id not found (specified in error response)
    • 400 - jurisdiction_id was not provided (specified in error response)
    • 400 - General Service error (Any failure during service query processing. Client will have to notify us)


Example response: 

<?xml version="1.0" encoding="utf-8"?>
<service_requests>
<request>
	<service_request_id>638344</service_request_id>
	<status>closed</status>
	<status_notes>Duplicate request.</status_notes>
	<service_name>Sidewalk and Curb Issues</service_name>
	<service_code>006</service_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>
	<media_url>http://open311.city.gov.s3.amazonaws.com/requests/media/638344.rss </media_url>
</request>
<request>
	<service_request_id>638349</service_request_id>
	<status>open</status>
	<status_notes></status_notes>
	<service_name>Sidewalk and Curb Issues</service_name>
	<service_code>006</service_code>
	<description></description>
	<agency_responsible></agency_responsible>
	<service_notice></service_notice>
	<requested_datetime>2010-04-19T06:37:38-08:00</requested_datetime>
	<updated_datetime>2010-04-19T06:37:38-08:00</updated_datetime>
	<expected_datetime>2010-04-19T06: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>
	<media_url>http://open311.city.gov.s3.amazonaws.com/requests/media/638349.rss </media_url>
</request>
</service_requests>

GET Service Request

  • Required Arguments:
    • service_request_id
    • jurisdiction_id
  • Optional Arguments:
    • none
  • 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
    • media_url (URL to media RSS feed of media associated with the request, eg an image)
  • Possible Errors (with HTTP status codes)
    • 404 - jurisdiction_id not found (specified in error response)
    • 400 - jurisdiction_id was not provided (specified in error response)
    • 400 - General Service error (Any failure during service query processing. Client will have to notify us)


Example response: 

<?xml version="1.0" encoding="utf-8"?>
<service_requests>
<request>
	<service_request_id>638344</service_request_id>
	<status>closed</status>
	<status_notes>Duplicate request.</status_notes>
	<service_name>Sidewalk and Curb Issues</service_name>
	<service_code>006</service_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>
	<media_url>http://open311.city.gov.s3.amazonaws.com/requests/media/638344.rss </media_url>
</request>

</service_requests>

Errors

Response:

  • status code - returned in HTTP header as HTTP status code
  • error (description of error)
  • General Errors
    • 403 - Missing or Invalid API Key (specify in error message)
    • 400 - The URL request is invalid or open311 service is not running or reachable. Client should notify us after checking URL

Example: 

HTTP/1.1 403 Forbidden 

<?xml version="1.0" encoding="utf-8"?>
<error>Invalid api_key received -- can't proceed with create_request.</error>
Retrieved from "https://wiki-archive.open311.org/index.php?title=GeoReport_v2_Draft&oldid=690"