Open311

Wiki

Collaboration for an Open311 Standard
Personal tools

Difference between revisions of "GeoReport v2"

Collaboration for an Open311 Standard

Jump to: navigation, search
(→‎Servers (can receive reports))
(expanding the introduction and API overview)
 
(12 intermediate revisions by one user not shown)
Line 1: Line 1:
 
  This spec has been frozen and finalized, but the documentation will continue to be updated for clarity. Join the [http://lists.open311.org/groups/discuss Mailing List] for updates.
 
  This spec has been frozen and finalized, but the documentation will continue to be updated for clarity. Join the [http://lists.open311.org/groups/discuss Mailing List] for updates.
  
−
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 v2 allows developers to build applications to both view and report issues which government entities like cities are responsible for addressing. These interactions are often referred to as "service requests" or "calls for service" and have traditionally been handled by custom web forms or phone based call centers (sometimes using the 311 phone number or other short-code). The GeoReport API is designed to allow both government and third party developers to create new applications and technologies that can integrate directly with these same official contact centers in any government that supports the standard. The current specification is focused on location-based non-emergency issues such as graffiti, potholes, and street cleaning.
 +
 
 +
The API consists of two main kinds of resources: <span class="strict-value">services</span> and service <span class="strict-value">requests</span>, but some servers that can't generate a realtime service request may also rely on a <span class="strict-value">token</span> resource. In total there are six methods used to interact with these resources: GET services, GET a service definition (a specific service_code id), POST a request, GET requests, GET a request (a specific service_request_id). The documentation below (starting from the API Methods section) is ordered based on a common sequence of interactions where a person first sees a list of available service types, selects one and creates a new service request, and then is able to track the status of that request and other requests. However each method can be accessed independently and some applications may only be focused on querying existing service requests to do analytics.
  
 
==Status==
 
==Status==
Line 8: Line 10:
 
<span style="color:orange;font-weight:bold">Stable:</span> The GeoReport v2 Spec has been finalized, but we are still updating documentation for clarity and verifying compliance of implementations
 
<span style="color:orange;font-weight:bold">Stable:</span> The GeoReport v2 Spec has been finalized, but we are still updating documentation for clarity and verifying compliance of implementations
  
−
===Servers (can receive reports)===
+
===Servers===
 
  <onlyinclude>
 
  <onlyinclude>
−
Servers receive and manage reports on behalf of a jurisdiction. '''A comprehensive list is being maintained on the [[GeoReport v2/Servers |GeoReport v2 Servers ]] page'''
+
Servers receive and manage service requests on behalf of a jurisdiction. '''A comprehensive list is being maintained on the [[GeoReport v2/Servers |GeoReport v2 Servers ]] page'''
 
</onlyinclude>
 
</onlyinclude>
  
−
==Developer Resources==
+
==Apps & Resources==
−
Please contribute to the full [[GeoReport v2/Resources |resources]] page.  
+
* See the [[GeoReport v2/Resources | GeoReport v2 Developer Resources]] page for code libraries and open source applications.  
−
 
+
* See the [[GeoReport v2/Support | GeoReport v2 Support]] page for applications, products, and services that support the spec.
−
{{:GeoReport v2/Resources}}
+
  
 
==Service Discovery==
 
==Service Discovery==
Line 59: Line 60:
  
 
====jurisdiction_id====
 
====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.
+
As a means to allow this API to distinguish multiple jurisdictions within one API endpoint 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 Arguments====
Line 67: Line 68:
  
 
===GET Service List===
 
===GET Service List===
−
*'''Purpose:''' provide a list of acceptable 311 service request types and their associated service codes. These request types can be unique to the city/jurisdiction.
+
{| class="spec-table" class="method-table"
−
* '''URL: ''' https://[API endpoint]/services.[format]
+
!scope="row" | Purpose
−
*'''Sample URL:''' <nowiki>https://api.city.gov/dev/v2/services.xml?jurisdiction_id=city.gov</nowiki>
+
| provide a list of acceptable 311 service request types and their associated service codes. These request types can be unique to the city/jurisdiction.
−
*'''Formats: '''XML (JSON available if denoted by [[Service Discovery]])
+
|-
−
*'''HTTP Method: '''GET
+
!scope="row" | URL
−
*'''Requires API Key: '''No
+
| https://[API endpoint]/services.[format]
 +
|-
 +
!scope="row" | Sample URL
 +
|  <nowiki>https://api.city.gov/dev/v2/services.xml?jurisdiction_id=city.gov</nowiki>
 +
|-
 +
!scope="row" | Formats
 +
|  XML (JSON available if denoted by [[Service Discovery]])
 +
|-
 +
!scope="row" | HTTP Method
 +
| GET
 +
|-
 +
!scope="row" | Requires API Key
 +
| No
 +
|}
 +
 
  
 
====Required Arguments====
 
====Required Arguments====
−
* '''jurisdiction_id'''
+
{| class="spec-table arguments-table"
 +
! Field Name
 +
! class="spec-description"|Description
 +
! class="spec-requirements"| Notes & Requirements
 +
|-
 +
| class="field" |
 +
; jurisdiction_id
 +
|
 +
| <span style="color: red">This is only required if the endpoint serves multiple jurisdictions</span>
 +
|}
  
 
====Response====
 
====Response====
−
*'''services'''
+
{| class="spec-table"
−
**Explanation: root element
+
! Field Name
−
*'''service'''
+
! class="spec-description"|Description
−
**Parent: services
+
! class="spec-requirements"| Notes & Requirements
−
**Explanation: container for service_code, service_name, description, metadata, type, keywords, group
+
|-
−
*'''service_code'''
+
!colspan="3" class="response-container"|services ⇊
−
**Parent: service
+
|-
−
**Explanation: The unique identifier for the service request type
+
!colspan="3" class="response-container"|service ↴
−
*'''service_name'''
+
|-
−
**Parent: service
+
| class="field" |
−
**Explanation: The human readable name of the service request type
+
; service_code
−
*'''description'''
+
| The unique identifier for the service request type
−
**Parent: service
+
|
−
**Explanation: A brief description of the service request type.
+
|-
−
*'''metadata'''
+
| class="field" |
−
**Parent: service
+
; service_name
−
**Explanation: Possible values: true, false
+
| The human readable name of the service request type
−
***true: This service request type requires additional metadata so the client will need to make a call to the [[#GET Service Definition|Service Definition]] method
+
|
−
***false: No additional information is required and a call to the [[#GET Service Definition|Service Definition]] method is not needed.
+
|-
−
*'''type'''
+
| class="field" |
−
**Parent: service
+
;  description
−
**Explanation: Possible values: realtime, batch, blackbox
+
| A brief description of the service request type.
−
***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
+
| class="field" |
−
**Explanation:
+
; metadata
−
*'''keywords'''
+
| Determines whether there are additional form fields for this service type.
−
**Parent: service
+
* <span class="strict-value">true</span>: This service request type requires additional metadata so the client will need to make a call to the [[#GET Service Definition|Service Definition]] method.
−
**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.
+
* <span class="strict-value">false</span>: No additional information is required and a call to the [[#GET Service Definition|Service Definition]] method is not needed.
−
*'''group'''
+
| Possible values: <span class="strict-value">true</span>, <span class="strict-value">false</span>.
−
**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"
+
| class="field" |
 +
; type
 +
|
 +
* <span class="strict-value">realtime</span>: The service request ID will be returned immediately after the service request is submitted.
 +
* <span class="strict-value">batch</span>: 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.  
 +
* <span class="strict-value">blackbox</span>: No service request ID will be returned after the service request is submitted
 +
| Possible values: <span class="strict-value">realtime</span>, <span class="strict-value">batch</span>, <span class="strict-value">blackbox</span>.
 +
|-
 +
| class="field" |
 +
; keywords
 +
| 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.
 +
|
 +
|-
 +
| class="field" |
 +
; group
 +
| 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====
 
====Possible Errors====
Line 192: Line 233:
  
 
===GET Service Definition===
 
===GET Service Definition===
−
*'''Conditional:''' Yes - <span style="font-weight : bold; color: red">This call is only necessary if the Service selected has metadata set as ''true'' from the ''GET Services'' response</span>
+
{| class="spec-table" class="method-table"
−
*'''Purpose:''' define attributes associated with a service code. These attributes can be unique to the city/jurisdiction.
+
!scope="row" | Conditional
−
*'''URL:''' https://[API endpoint]/services/[service_code].[format]
+
| Yes - <span style="font-weight : bold; color: red">This call is only necessary if the Service selected has metadata set as ''true'' from the ''GET Services'' response</span>
−
*'''Sample URL: ''' <nowiki>https://api.city.gov/dev/v2/services/033.xml?jurisdiction_id=city.gov</nowiki>
+
|-
−
*'''Formats:''' XML (JSON available if denoted by [[Service Discovery]])
+
!scope="row" | Purpose
−
*'''HTTP Method:''' GET
+
| Define attributes associated with a service code. These attributes can be unique to the city/jurisdiction.
−
*'''Requires API Key:''' No
+
|-
 +
!scope="row" | URL
 +
| https://[API endpoint]/services/[service_code].[format]
 +
|-
 +
!scope="row" | Sample URL
 +
|  <nowiki>https://api.city.gov/dev/v2/services/033.xml?jurisdiction_id=city.gov</nowiki>
 +
|-
 +
!scope="row" | Formats
 +
|  XML (JSON available if denoted by [[Service Discovery]])
 +
|-
 +
!scope="row" | HTTP Method
 +
| GET
 +
|-
 +
!scope="row" | Requires API Key
 +
| No
 +
|}
 +
 
  
 
====Required Arguments====
 
====Required Arguments====
−
* service_code
+
{| class="spec-table arguments-table"
−
* jurisdiction_id
+
! Field Name
 +
! class="spec-description"|Description
 +
! class="spec-requirements"| Notes & Requirements
 +
|-
 +
| class="field" |
 +
; jurisdiction_id
 +
|
 +
| <span style="color: red">This is only required if the endpoint serves multiple jurisdictions</span>
 +
|-
 +
| class="field" |
 +
; <span class="field-url">service_code</span>
 +
|
 +
| The service_code is specified in the main URL path rather than an added query string parameter.
 +
|}
 +
 
 +
 
  
 
====Response====
 
====Response====
−
*'''service_definition'''
+
 
−
**Explanation: root element
+
{| class="spec-table"
−
*'''service_code'''
+
! Field Name
−
**Parent: service_definition
+
! class="spec-description"|Description
−
**Explanation: Returns the service_code associated with the definition, the same one submitted for this call.
+
! class="spec-requirements"| Notes & Requirements
−
*'''attributes'''
+
|-
−
**Parent: service_definition
+
!colspan="3" class="response-container"|service_definition ↴
−
**Explanation: container for attribute
+
|-
−
*'''attribute'''
+
| class="field" |
−
**Parent: attributes
+
; service_code
−
**Explanation: container for the following elements:
+
| Returns the service_code associated with the definition, the same one submitted for this call.
−
*'''variable'''
+
|
−
**Parent: attribute
+
|-
−
**Options: true, false
+
!colspan="3" class="response-container"|attributes ⇊
−
**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'''
+
!colspan="3" class="response-container"|attribute ↴
−
**Parent: attribute
+
|-
−
**Explanation: A unique identifier for the attribute
+
| class="field" |
−
*'''datatype'''
+
; variable
−
**Parent: attribute
+
|
−
**Options: string, number, datetime, text, singlevaluelist, multivaluelist
+
* <span class="strict-value">true</span> denotes that user input is needed
−
*** string: A string of characters without line breaks. Represented in an HTML from using an <input> tag
+
* <span class="strict-value">false</span> means the attribute is only used to present information to the user within the description field
−
*** number: A numeric value. Represented in an HTML from using an <input> tag
+
| Possible values: <span class="strict-value">true</span>, <span class="strict-value">false</span>.
−
*** 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
+
| class="field" |
−
*** 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
+
; code
−
*** 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
+
| A unique identifier for the attribute
−
**Explanation: Denotes the type of field used for user input.  
+
|
−
*'''required'''
+
|-
−
**Parent: attribute
+
| class="field" |
−
**Options: true, false
+
; datatype
−
**Explanation: Setting true means that the value is required to submit service request
+
| Denotes the type of field used for user input.
−
*'''datatype_description'''
+
* <span class="strict-value">string</span>: A string of characters without line breaks. Represented in an HTML form using an <input> tag
−
**Parent: attribute
+
* <span class="strict-value">number</span>: A numeric value. Represented in an HTML form using an <input> tag
−
**Explanation: A description of the datatype which helps the user provide their input
+
* <span class="strict-value">datetime</span>: The input generated must be able to transform into a valid ISO 8601 date. Represented in an HTML form using <input> tags
−
*'''order'''
+
* <span class="strict-value">text</span>:  A string of characters that may contain line breaks. Represented in an HTML form using an <textarea> tag
−
**Parent: attribute
+
* <span class="strict-value">singlevaluelist</span>:  A set of predefined values (specified in this response) where only one value may be selected. Represented in an HTML form using the <select> and <option> tags
−
**Options: Any positive integer not used for other attributes in the same service_code
+
* <span class="strict-value">multivaluelist</span>:  A set of predefined values (specified in this response) where several values may be selected. Represented in an HTML form using the <select multiple="multiple"> and <option> tags
−
**Explanation: The sort order that the attributes will be presented to the user. 1 is shown first
+
| Options: <span class="strict-value">string</span>, <span class="strict-value">number</span>, <span class="strict-value">datetime</span>, <span class="strict-value">text</span>, <span class="strict-value">singlevaluelist</span>, <span class="strict-value">multivaluelist</span>.
−
*'''description'''
+
|-
−
**Parent: attribute
+
| class="field" |
−
**Explanation: An description of the attribute field with instructions for the user to find and identify the requested information
+
; required
−
*'''values'''
+
|
−
**Parent: attribute
+
* <span class="strict-value">true</span> means that the value is required to submit service request
−
**Explanation: A container for a list of predefined options for singlevaluelist or multivaluelist. Required if datatype is set to singlevaluelist or multivaluelist.
+
* <span class="strict-value">false</span> means that the value not required.
−
*'''value'''
+
| Options: <span class="strict-value">true</span>, <span class="strict-value">false</span>.
−
**Parent: values
+
|-
−
**Explanation: A container for a predefined option (key and name) for singlevaluelist or multivaluelist
+
| class="field" |
−
*'''key'''
+
; datatype_description
−
**Parent: value
+
| A description of the datatype which helps the user provide their input
−
**Explanation: The unique identifier associated with an option for singlevaluelist or multivaluelist. This is analogous to the value attribute in an html option tag.
+
|
−
*'''name'''
+
|-
−
**Parent: value
+
| class="field" |
−
**Explanation: The human readable title of an option for singlevaluelist or multivaluelist. This is analogous to the innerhtml text node of an html option tag.
+
; order
 +
| The sort order that the attributes will be presented to the user. 1 is shown first in the list.
 +
| Any positive integer not used for other attributes in the same service_code
 +
|-
 +
| class="field" |
 +
; description
 +
| An description of the attribute field with instructions for the user to find and identify the requested information
 +
|
 +
|-
 +
!colspan="3" class="response-container"| values ⇊
 +
|-
 +
!colspan="3" class="response-container"| value ↴
 +
|-
 +
| class="field" |
 +
; key
 +
| The unique identifier associated with an option for singlevaluelist or multivaluelist. This is analogous to the value attribute in an html option tag.
 +
|
 +
|-
 +
| class="field" |
 +
; name
 +
| The human readable title of an option for singlevaluelist or multivaluelist. This is analogous to the innerhtml text node of an html option tag.
 +
|
 +
|}
  
  
Line 333: Line 427:
  
 
===POST Service Request===
 
===POST Service Request===
−
*'''Purpose:''' Create service requests
+
{| class="spec-table" class="method-table"
−
*'''URL:''' https://[API endpoint]/requests.[format]
+
!scope="row" | Purpose
−
*'''Sample URL:''' <nowiki>https://api.city.gov/dev/v2/requests.xml</nowiki>
+
| Create service requests
−
*'''Format sent:''' Content-Type: application/x-www-form-urlencoded
+
|-
−
*'''Formats returned:''' XML (JSON available if denoted by [[Service Discovery]])
+
!scope="row" | URL
−
*'''HTTP Method:''' POST
+
| https://[API endpoint]/requests.[format]
−
*'''Requires API Key:''' Yes
+
|-
 +
!scope="row" | Sample URL
 +
|  <nowiki>https://api.city.gov/dev/v2/requests.xml</nowiki>
 +
|-
 +
!scope="row" | Format sent
 +
|  Content-Type: application/x-www-form-urlencoded
 +
|-
 +
!scope="row" | Formats returned
 +
|  XML (JSON available if denoted by [[Service Discovery]])
 +
|-
 +
!scope="row" | HTTP Method
 +
| POST
 +
|-
 +
!scope="row" | Requires API Key
 +
| Yes
 +
|}
 +
 
  
 
====Required Arguments====
 
====Required Arguments====
−
* '''jurisdiction_id'''
+
{| class="spec-table arguments-table"
−
* '''service_code''' (obtained from [[#GET_Service_List|GET Service List]] method)
+
! Field Name
−
* location: either '''lat''' & '''long''' or '''address_string''' or '''address_id''' must be submitted
+
! class="spec-description"|Description
−
* '''attribute''' - <span style="color:red">only required if the service_code requires a service definition with required fields</span>
+
! class="spec-requirements"| Notes & Requirements
−
**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 as well as multiple values for the same code in the case of a multivaluelist datatype (attribute[code1][]=value1&attribute[code1][]=value2&attribute[code1][]=value3) - see example
+
|-
 +
| class="field" |
 +
;jurisdiction_id
 +
|
 +
| <span style="color: red">This is only required if the endpoint serves multiple jurisdictions</span>
 +
|-
 +
| class="field" |
 +
;service_code
 +
|
 +
| This is obtained from [[#GET_Service_List|GET Service List]] method
 +
|-
 +
| class="field" |
 +
;<span class="field-alternatives">location parameter</span>
 +
| A full location parameter must be submitted.
 +
| One of <span class="strict-value">lat</span> & <span class="strict-value">long</span> or <span class="strict-value">address_string</span> or <span class="strict-value">address_id</span>
 +
|-
 +
| class="field" |
 +
;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 as well as multiple values for the same code in the case of a multivaluelist datatype (attribute[code1][]=value1&attribute[code1][]=value2&attribute[code1][]=value3) - see example. <br /><span style="color:red">This is only required if the service_code requires a service definition with required fields</span>.
 +
|}
  
  
 
====Optional Arguments====
 
====Optional Arguments====
−
* '''lat'''
+
{| class="spec-table arguments-table"
−
**Explanation: latitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
+
! Field Name
−
* '''long'''
+
! class="spec-description"|Description
−
**Explanation: longitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
+
! class="spec-requirements"| Notes & Requirements
−
* '''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.
+
| class="field" |
−
* '''address_id'''
+
;lat
−
**Explanation: The internal address ID used by a jurisdictions master address repository or other addressing system.  
+
| Latitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
−
* '''email'''
+
| <span class="strict-value">lat</span> & <span class="strict-value">long</span> both need to be sent even though they are sent as two separate parameters. <span class="strict-value">lat</span> & <span class="strict-value">long</span> are required if no <span class="strict-value">address_string</span> or <span class="strict-value">address_id</span> is provided.
−
**Explanation: The email address of the person submitting the request
+
|-
−
* '''device_id'''
+
| class="field" |
−
**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
+
;long
−
* '''account_id'''
+
| Longitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
−
**Explanation: The unique ID for the user account of the person submitting the request
+
| <span class="strict-value">lat</span> & <span class="strict-value">long</span> both need to be sent even though they are sent as two separate parameters. <span class="strict-value">lat</span> & <span class="strict-value">long</span> are required if no <span class="strict-value">address_string</span> or <span class="strict-value">address_id</span> is provided.
−
* '''first_name'''
+
|-
−
**Explanation: The given name of the person submitting the request
+
| class="field" |
−
* '''last_name'''
+
;address_string
−
**Explanation: The family name of the person submitting the request
+
| Human entered address or description of location.
−
* '''phone'''
+
| This is required if no <span class="strict-value">lat</span>/<span class="strict-value">long</span> or <span class="strict-value">address_id</span> are provided. 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.  
−
**Explanation: The phone number of the person submitting the request
+
|-
−
* '''description'''
+
| class="field" |
−
**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.
+
;address_id
−
* '''media_url'''
+
| The internal address ID used by a jurisdiction's master address repository or other addressing system.  
−
**Explanation: A URL to media associated with the request, eg an image. A convention for parsing media from this URL has yet to be established, so currently it will be done on a case by case basis. For example, if a jurisdiction accepts photos submitted via Twitpic.com, then clients can parse the page at the Twitpic URL for the image given the conventions of Twitpic.com. This could also be a URL to a media RSS feed where the clients can parse for media in a more structured way.
+
| This is required if no <span class="strict-value">lat</span>/<span class="strict-value">long</span> or <span class="strict-value">address_string</span> are provided.
 +
|-
 +
| class="field" |
 +
;email
 +
| The email address of the person submitting the request
 +
|
 +
|-
 +
| class="field" |
 +
;device_id
 +
| The unique device ID of the device submitting the request. This is usually only used for mobile devices.  
 +
| Android devices can use TelephonyManager.getDeviceId() and iPhones can use [UIDevice currentDevice].uniqueIdentifier
 +
|-
 +
| class="field" |
 +
;account_id
 +
| The unique ID for the user account of the person submitting the request
 +
|
 +
|-
 +
| class="field" |
 +
;first_name
 +
| The given name of the person submitting the request
 +
|
 +
|-
 +
| class="field" |
 +
;last_name
 +
| The family name of the person submitting the request
 +
|
 +
|-
 +
| class="field" |
 +
;phone
 +
| The phone number of the person submitting the request
 +
|
 +
|-
 +
| class="field" |
 +
;description
 +
| 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.
 +
|-
 +
| class="field" |
 +
;media_url
 +
| A URL to media associated with the request, eg an image.  
 +
| A convention for parsing media from this URL has yet to be established, so currently it will be done on a case by case basis much like Twitter.com does. For example, if a jurisdiction accepts photos submitted via Twitpic.com, then clients can parse the page at the Twitpic URL for the image given the conventions of Twitpic.com. This could also be a URL to a media RSS feed where the clients can parse for media in a more structured way.
 +
|}
 +
 
 +
 
  
 
====Response====
 
====Response====
−
*'''service_requests'''
+
{| class="spec-table"
−
**Explanation: root element
+
! Field Name
−
*'''request'''
+
! class="spec-description"|Description
−
**Parent: service_requests
+
! class="spec-requirements"| Notes & Requirements
−
**Explanation: container for service_request_id, token, service_notice, account_id
+
|-
−
*'''service_request_id'''
+
!colspan="3" class="response-container"|service_requests ⇊
−
**Parent: request
+
|-
−
**Explanation: The unique ID of the service request created. This will not be returned if token is returned
+
!colspan="3" class="response-container"|request ↴
−
*'''token'''
+
|-
−
**Parent: request
+
| class="field" |
−
**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_request_id
−
*'''service_notice'''
+
| The unique ID of the service request created.
−
**Parent: request
+
| <span style="color: red">This should not be returned if token is returned</span>
−
**Explanation: Information about the action expected to fulfill the request or otherwise address the information reported. (may not be returned)
+
|-
−
*'''account_id'''
+
| class="field" |
−
**Parent: request
+
;  token
−
**Explanation: The unique ID for the user account of the person submitting the request. (may not be returned)
+
| If returned, use this to call [[#GET_service_request_id_from_a_token|GET service_request_id from a token]].
 +
| <span style="color: red">This should not be returned if service_request_id is returned</span>
 +
|-
 +
| class="field" |
 +
;  service_notice
 +
| Information about the action expected to fulfill the request or otherwise address the information reported.  
 +
| May not be returned
 +
|-
 +
| class="field" |
 +
; account_id
 +
| The unique ID for the user account of the person submitting the request.  
 +
| May not be returned
 +
|}
 +
 
  
 
====Possible Errors====
 
====Possible Errors====
Line 441: Line 627:
 
</tabs>
 
</tabs>
  
−
===GET request_id from a token===
+
===GET service_request_id from a token===
−
*'''Conditional:''' Yes - <span style="font-weight : bold; color: red">This call is only necessary if the response from ''POST Service Request'' contains a token</span>
+
{| class="spec-table" class="method-table"
−
*'''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.  
+
!scope="row" | Conditional
−
*'''URL:''' https://[API endpoint]/tokens/[token id].[format]
+
| Yes - <span style="font-weight : bold; color: red">This call is only necessary if the response from ''POST Service Request'' contains a token</span>
−
*'''Sample URL:'''  <nowiki>https://api.city.gov/dev/v2/tokens/123456.xml?jurisdiction_id=city.gov</nowiki>
+
|-
−
*'''Formats: '''XML (JSON available if denoted by [[Service Discovery]])
+
!scope="row" | Purpose
−
*'''HTTP Method: '''GET
+
| Get the service_request_id from a temporary token. This is unnecessary if the response from creating a service request does not contain a token.  
−
*'''Requires API Key: '''No
+
|-
 +
!scope="row" | URL
 +
| https://[API endpoint]/tokens/[token id].[format]
 +
|-
 +
!scope="row" | Sample URL
 +
|  <nowiki>https://api.city.gov/dev/v2/tokens/123456.xml?jurisdiction_id=city.gov</nowiki>
 +
|-
 +
!scope="row" | Formats
 +
|  XML (JSON available if denoted by [[Service Discovery]])
 +
|-
 +
!scope="row" | HTTP Method
 +
| GET
 +
|-
 +
!scope="row" | Requires API Key
 +
| No
 +
|}
 +
 
  
 
====Required Arguments====
 
====Required Arguments====
−
* '''jurisdiction_id'''
+
{| class="spec-table arguments-table"
−
* '''token'''
+
! Field Name
 +
! class="spec-description"|Description
 +
! class="spec-requirements"| Notes & Requirements
 +
|-
 +
| class="field" |
 +
;jurisdiction_id
 +
|
 +
| <span style="color: red">This is only required if the endpoint serves multiple jurisdictions</span>
 +
|-
 +
| class="field" |
 +
;<span class="field-url">token</span>
 +
|
 +
| This is obtained from the [[#POST_Service_Requests|POST Service Requests]] method
 +
|}
 +
 
  
 
====Response====
 
====Response====
−
*'''service_requests'''
+
{| class="spec-table"
−
**Explanation: root element
+
! Field Name
−
*'''request'''
+
! class="spec-description"|Description
−
**Parent: service_requests
+
! class="spec-requirements"| Notes & Requirements
−
**Explanation: container for service_request_id, token
+
|-
−
*'''service_request_id'''
+
!colspan="3" class="response-container"|service_requests ⇊
−
**Parent: request
+
|-
−
**Explanation: The unique ID for the service request created. This can be used to call the [[#GET_Service_Request|GET Service Request]] method.
+
!colspan="3" class="response-container"|request ↴
−
*'''token'''
+
|-
−
**Parent: request
+
| class="field" |
−
**Explanation: The token ID used to make this call.
+
; service_request_id
 +
| The unique ID for the service request created. This can be used to call the [[#GET_Service_Request|GET Service Request]] method.
 +
|
 +
|-
 +
| class="field" |
 +
; token
 +
| The token ID used to make this call.
 +
|
 +
|}
 +
 
  
 
====Possible Errors====
 
====Possible Errors====
Line 500: Line 725:
  
 
===GET Service Requests===
 
===GET Service Requests===
−
*'''Purpose:''' query the current status of multiple requests
+
{| class="spec-table" class="method-table"
−
*'''URL:''' https://[API endpoint]/requests.[format]
+
!scope="row" | Purpose
−
*'''Sample URL:'''  <nowiki>https://api.city.gov/dev/v2/requests.xml?start_date=2010-05-24T00:00:00Z&end_date=2010-06-24T00:00:00Z&status=open&jurisdiction_id=city.gov</nowiki>
+
| Query the current status of multiple requests
−
*'''Formats: '''XML (JSON available if denoted by [[Service Discovery]])
+
|-
−
*'''HTTP Method: '''GET
+
!scope="row" | URL
−
*'''Requires API Key: '''No
+
| https://[API endpoint]/requests.[format]
 +
|-
 +
!scope="row" | Sample URL
 +
|  <nowiki>https://api.city.gov/dev/v2/requests.xml?start_date=2010-05-24T00:00:00Z&end_date=2010-06-24T00:00:00Z&status=open&jurisdiction_id=city.gov</nowiki>
 +
|-
 +
!scope="row" | Formats
 +
|  XML (JSON available if denoted by [[Service Discovery]])
 +
|-
 +
!scope="row" | HTTP Method
 +
| GET
 +
|-
 +
!scope="row" | Requires API Key
 +
| No
 +
|}
 +
 
  
 
====Required Arguments====
 
====Required Arguments====
−
* '''jurisdiction_id'''
+
{| class="spec-table arguments-table"
 +
! Field Name
 +
! class="spec-description"|Description
 +
! class="spec-requirements"| Notes & Requirements
 +
|-
 +
| class="field" |
 +
;jurisdiction_id
 +
|
 +
| <span style="color: red">This is only required if the endpoint serves multiple jurisdictions</span>
 +
|}
  
 
====Optional Arguments====
 
====Optional Arguments====
−
* '''service_request_id'''
+
{| class="spec-table arguments-table"
−
** Explanation: To call multiple Service Requests at once, multiple service_request_id can be declared; comma delimited. This overrides all other arguments.
+
! Field Name
−
* '''service_code'''
+
! class="spec-description"|Description
−
** Explanation: Specify the service type by calling the unique ID of the service_code. This defaults to all service codes when not declared; can be declared multiple times, comma delimited
+
! class="spec-requirements"| Notes & Requirements
−
* '''start_date'''
+
|-
−
** Explanation: Earliest datetime to include in search. When provided with end_date, allows one to search for requests which have a requested_datetime that matches a given range, but may not span more than 90 days. When not specified, the range defaults to most recent 90 days. Must use w3 format, eg 2010-01-01T00:00:00Z.
+
| class="field" |
−
* '''end_date'''
+
;service_request_id
−
** Explanation: Latest datetime to include in search. When provided with start_date, allows one to search for requests which have a requested_datetime that matches a given range, but may not span more than 90 days. When not specified, the range defaults to most recent 90 days. Must use w3 format, eg 2010-01-01T00:00:00Z.
+
| To call multiple Service Requests at once, multiple service_request_id can be declared; comma delimited.  
−
* '''status'''
+
| This overrides all other arguments.
−
** Options: open, closed
+
|-
−
** Explanation: Allows one to search for requests which have a specific status. This defaults to all statuses; can be declared multiple times, comma delimited;
+
| class="field" |
 +
;service_code
 +
| Specify the service type by calling the unique ID of the service_code.  
 +
| This defaults to all service codes when not declared; can be declared multiple times, comma delimited
 +
|-
 +
| class="field" |
 +
;start_date
 +
| Earliest datetime to include in search. When provided with end_date, allows one to search for requests which have a requested_datetime that matches a given range, but may not span more than 90 days.  
 +
| When not specified, the range defaults to most recent 90 days. Must use w3 format, eg 2010-01-01T00:00:00Z.
 +
|-
 +
| class="field" |
 +
;end_date
 +
| Latest datetime to include in search. When provided with start_date, allows one to search for requests which have a requested_datetime that matches a given range, but may not span more than 90 days.  
 +
| When not specified, the range defaults to most recent 90 days. Must use w3 format, eg 2010-01-01T00:00:00Z.
 +
|-
 +
| class="field" |
 +
;status
 +
| Allows one to search for requests which have a specific status. This defaults to all statuses; can be declared multiple times, comma delimited;
 +
| Options: <span class="strict-value">open</span>, <span class="strict-value">closed</span>
 +
|}
  
 
====Response====
 
====Response====
−
*'''service_requests'''
+
{| class="spec-table"
−
**Explanation: root element
+
! Field Name
−
*'''request'''
+
! class="spec-description"|Description
−
**Parent: service_requests
+
! class="spec-requirements"| Notes & Requirements
−
**Explanation: container for variable, code, datatype, required, datatype_description, order, description, values
+
|-
−
* '''service_request_id'''
+
!colspan="3" class="response-container"|service_requests ⇊
−
** Parent: request
+
|-
−
**Explanation: The unique ID for the service request returned
+
!colspan="3" class="response-container"|request ↴
−
* '''status'''
+
|-
−
** Parent: request
+
| class="field" |
−
**Options: open, closed
+
; service_request_id
−
**Explanation: The current status of the service request. Open means that it has been reported. Closed means that it has been resolved.
+
| The unique ID of the service request created.
−
* '''status_notes'''
+
|
−
** Parent: request
+
|-
−
**Explanation: Explanation of why status was changed to current state or more details on current status than conveyed with status alone. (May not be returned)
+
| class="field" |
−
* '''service_name'''
+
; status
−
** Parent: request''
+
| The current status of the service request.  
−
**Explanation: The human readable name of the service request type  
+
* <span class="strict-value">open</span>: it has been reported.  
−
* '''service_code'''
+
* <span class="strict-value">closed</span>: it has been resolved.
−
** Parent: request
+
| Options: <span class="strict-value">open</span>, <span class="strict-value">closed</span>
−
** Explanation: The unique identifier for the service request type  
+
|-
−
* '''description'''
+
| class="field" |
−
** Parent: request
+
; status_notes
−
** Explanation: A full description of the request or report submitted. This may contain line breaks, but not html or code. Otherwise, this is free form text limited to 4,000 characters.
+
| Explanation of why status was changed to current state or more details on current status than conveyed with status alone.
−
* '''agency_responsible'''
+
| May not be returned
−
** Parent: request
+
|-
−
** Explanation: The agency responsible for fulfilling or otherwise addressing the service request. (May not be returned)
+
| class="field" |
−
* '''service_notice'''
+
; service_name
−
** Parent: request
+
| The human readable name of the service request type  
−
** Explanation: Information about the action expected to fulfill the request or otherwise address the information reported. (May not be returned)
+
|
−
* '''requested_datetime'''
+
|-
−
** Parent: request
+
| class="field" |
−
** Explanation: The date and time when the service request was made. Returned in w3 format, eg 2010-01-01T00:00:00Z
+
; service_code
−
* '''updated_datetime'''
+
| The unique identifier for the service request type
−
** Parent: request
+
|
−
** Explanation: The date and time when the service request was last modified. For requests with status=closed, this will be the date the request was closed. Returned in w3 format, eg 2010-01-01T00:00:00Z
+
|-
−
* '''expected_datetime'''
+
| class="field" |
−
** Parent: request
+
; description
−
** Explanation: The date and time when the service request can be expected to be fulfilled. This may be based on a service-specific service level agreement. (May not be returned)
+
| A full description of the request or report submitted.  
−
* '''address'''
+
| This may contain line breaks, but not html or code. Otherwise, this is free form text limited to 4,000 characters.
−
** Parent: request
+
|-
−
** Explanation: Human readable address or description of location. This should be provided from most specific to most general geographic unit, eg address number or cross streets, street name, neighborhood/district, city/town/village, county, postal code.  
+
| class="field" |
−
* '''address_id'''
+
; agency_responsible
−
** Parent: request
+
| The agency responsible for fulfilling or otherwise addressing the service request.  
−
** Explanation: The internal address ID used by a jurisdictions master address repository or other addressing system.  
+
| May not be returned
−
* '''zipcode'''
+
|-
−
** Parent: request
+
| class="field" |
−
** Explanation: The postal code for the location of the service request.
+
; service_notice
−
* '''lat'''
+
| Information about the action expected to fulfill the request or otherwise address the information reported.
−
** Parent: request
+
| May not be returned
−
** Explanation: latitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
+
|-
−
* '''long'''
+
| class="field" |
−
** Parent: request
+
; requested_datetime
−
** Explanation: longitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
+
| The date and time when the service request was made.  
−
* '''media_url'''
+
| Returned in w3 format, eg 2010-01-01T00:00:00Z
−
** Parent: request
+
|-
−
**Explanation: A URL to media associated with the request, eg an image. A convention for parsing media from this URL has yet to be established, so currently it will be done on a case by case basis. For example, if a jurisdiction accepts photos submitted via Twitpic.com, then clients can parse the page at the Twitpic URL for the image given the conventions of Twitpic.com. This could also be a URL to a media RSS feed where the clients can parse for media in a more structured way.
+
| class="field" |
 +
; updated_datetime
 +
| The date and time when the service request was last modified. For requests with status=closed, this will be the date the request was closed.  
 +
| Returned in w3 format, eg 2010-01-01T00:00:00Z
 +
|-
 +
| class="field" |
 +
; expected_datetime
 +
| The date and time when the service request can be expected to be fulfilled. This may be based on a service-specific service level agreement.  
 +
| May not be returned
 +
|-
 +
| class="field" |
 +
; address
 +
| Human readable address or description of location.  
 +
| This should be provided from most specific to most general geographic unit, eg address number or cross streets, street name, neighborhood/district, city/town/village, county, postal code.  
 +
|-
 +
| class="field" |
 +
; address_id
 +
| The internal address ID used by a jurisdictions master address repository or other addressing system.  
 +
|
 +
|-
 +
| class="field" |
 +
; zipcode
 +
| The postal code for the location of the service request.
 +
|
 +
|-
 +
| class="field" |
 +
; lat
 +
| latitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
 +
|
 +
|-
 +
| class="field" |
 +
; long
 +
| longitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
 +
|
 +
|-
 +
| class="field" |
 +
; media_url
 +
| A URL to media associated with the request, eg an image.  
 +
| A convention for parsing media from this URL has yet to be established, so currently it will be done on a case by case basis much like Twitter.com does. For example, if a jurisdiction accepts photos submitted via Twitpic.com, then clients can parse the page at the Twitpic URL for the image given the conventions of Twitpic.com. This could also be a URL to a media RSS feed where the clients can parse for media in a more structured way.
 +
|}
 +
 
  
 
====Response Volume====
 
====Response Volume====
Line 687: Line 994:
  
 
===GET Service Request===
 
===GET Service Request===
−
*'''Purpose:''' query the current status of an individual request
+
{| class="spec-table" class="method-table"
−
*'''URL: ''' https://[API endpoint]/requests/[service_request_id].[format]
+
!scope="row" | Purpose
−
*'''Sample URL:'''  <nowiki>https://api.city.gov/dev/v2/requests/123456.xml?jurisdiction_id=city.gov</nowiki>
+
| Query the current status of an individual request
−
*'''Formats: '''XML (JSON available if denoted by [[Service Discovery]])
+
|-
−
*'''HTTP Method: '''GET
+
!scope="row" | URL
−
*'''Requires API Key: '''No
+
| https://[API endpoint]/requests/[service_request_id].[format]
 +
|-
 +
!scope="row" | Sample URL
 +
|  <nowiki>https://api.city.gov/dev/v2/requests/123456.xml?jurisdiction_id=city.gov</nowiki>
 +
|-
 +
!scope="row" | Formats
 +
|  XML (JSON available if denoted by [[Service Discovery]])
 +
|-
 +
!scope="row" | HTTP Method
 +
| GET
 +
|-
 +
!scope="row" | Requires API Key
 +
| No
 +
|}
 +
 
  
 
====Required Arguments====
 
====Required Arguments====
−
* '''service_request_id'''
+
{| class="spec-table arguments-table"
−
* '''jurisdiction_id'''
+
! Field Name
 +
! class="spec-description"|Description
 +
! class="spec-requirements"| Notes & Requirements
 +
|-
 +
| class="field" |
 +
;jurisdiction_id
 +
|
 +
| <span style="color: red">This is only required if the endpoint serves multiple jurisdictions</span>
 +
|-
 +
| class="field" |
 +
;<span class="field-url">service_request_id</span>
 +
|
 +
| The service_request_id is specified in the main URL path rather than an added query string parameter.
 +
|}
 +
 
  
 
====Optional Arguments====
 
====Optional Arguments====
−
* none
+
None
  
 
====Response====
 
====Response====
−
*'''service_requests'''
+
{| class="spec-table"
−
**Explanation: root element
+
! Field Name
−
*'''request'''
+
! class="spec-description"|Description
−
**Parent: service_requests
+
! class="spec-requirements"| Notes & Requirements
−
**Explanation: container for variable, code, datatype, required, datatype_description, order, description, values
+
|-
−
* '''service_request_id'''
+
!colspan="3" class="response-container"|service_requests ⇊
−
** Parent: request
+
|-
−
**Explanation: The unique ID for the service request returned
+
!colspan="3" class="response-container"|request ↴
−
* '''status'''
+
|-
−
** Parent: request
+
| class="field" |
−
**Options: open, closed
+
; service_request_id
−
**Explanation: The current status of the service request. Open means that it has been reported. Closed means that it has been resolved.
+
| The unique ID of the service request created.
−
* '''status_notes'''
+
|
−
** Parent: request
+
|-
−
**Explanation: Explanation of why status was changed to current state or more details on current status than conveyed with status alone. (May not be returned)
+
| class="field" |
−
* '''service_name'''
+
; status
−
** Parent: request''
+
| The current status of the service request.  
−
**Explanation: The human readable name of the service request type  
+
* <span class="strict-value">open</span>: it has been reported.  
−
* '''service_code'''
+
* <span class="strict-value">closed</span>: it has been resolved.
−
** Parent: request
+
| Options: <span class="strict-value">open</span>, <span class="strict-value">closed</span>
−
** Explanation: The unique identifier for the service request type  
+
|-
−
* '''description'''
+
| class="field" |
−
** Parent: request
+
; status_notes
−
** Explanation: A full description of the request or report submitted. This may contain line breaks, but not html or code. Otherwise, this is free form text limited to 4,000 characters.
+
| Explanation of why status was changed to current state or more details on current status than conveyed with status alone.
−
* '''agency_responsible'''
+
| May not be returned
−
** Parent: request
+
|-
−
** Explanation: The agency responsible for fulfilling or otherwise addressing the service request. (May not be returned)
+
| class="field" |
−
* '''service_notice'''
+
; service_name
−
** Parent: request
+
| The human readable name of the service request type  
−
** Explanation: Information about the action expected to fulfill the request or otherwise address the information reported. (May not be returned)
+
|
−
* '''requested_datetime'''
+
|-
−
** Parent: request
+
| class="field" |
−
** Explanation: The date and time when the service request was made. Returned in w3 format, eg 2010-01-01T00:00:00Z
+
; service_code
−
* '''updated_datetime'''
+
| The unique identifier for the service request type
−
** Parent: request
+
|
−
** Explanation: The date and time when the service request was last modified. For requests with status=closed, this will be the date the request was closed. Returned in w3 format, eg 2010-01-01T00:00:00Z
+
|-
−
* '''expected_datetime'''
+
| class="field" |
−
** Parent: request
+
; description
−
** Explanation: The date and time when the service request can be expected to be fulfilled. This may be based on a service-specific service level agreement. (May not be returned)
+
| A full description of the request or report submitted.  
−
* '''address'''
+
| This may contain line breaks, but not html or code. Otherwise, this is free form text limited to 4,000 characters.
−
** Parent: request
+
|-
−
** Explanation: Human readable address or description of location. This should be provided from most specific to most general geographic unit, eg address number or cross streets, street name, neighborhood/district, city/town/village, county, postal code.  
+
| class="field" |
−
* '''address_id'''
+
; agency_responsible
−
** Parent: request
+
| The agency responsible for fulfilling or otherwise addressing the service request.  
−
** Explanation: The internal address ID used by a jurisdictions master address repository or other addressing system.  
+
| May not be returned
−
* '''zipcode'''
+
|-
−
** Parent: request
+
| class="field" |
−
** Explanation: The postal code for the location of the service request.
+
; service_notice
−
* '''lat'''
+
| Information about the action expected to fulfill the request or otherwise address the information reported.
−
** Parent: request
+
| May not be returned
−
** Explanation: latitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
+
|-
−
* '''long'''
+
| class="field" |
−
** Parent: request
+
; requested_datetime
−
** Explanation: longitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
+
| The date and time when the service request was made.  
−
* '''media_url'''
+
| Returned in w3 format, eg 2010-01-01T00:00:00Z
−
** Parent: request
+
|-
−
**Explanation: A URL to media associated with the request, eg an image. A convention for parsing media from this URL has yet to be established, so currently it will be done on a case by case basis. For example, if a jurisdiction accepts photos submitted via Twitpic.com, then clients can parse the page at the Twitpic URL for the image given the conventions of Twitpic.com. This could also be a URL to a media RSS feed where the clients can parse for media in a more structured way.
+
| class="field" |
 +
; updated_datetime
 +
| The date and time when the service request was last modified. For requests with status=closed, this will be the date the request was closed.  
 +
| Returned in w3 format, eg 2010-01-01T00:00:00Z
 +
|-
 +
| class="field" |
 +
; expected_datetime
 +
| The date and time when the service request can be expected to be fulfilled. This may be based on a service-specific service level agreement.  
 +
| May not be returned
 +
|-
 +
| class="field" |
 +
; address
 +
| Human readable address or description of location.  
 +
| This should be provided from most specific to most general geographic unit, eg address number or cross streets, street name, neighborhood/district, city/town/village, county, postal code.  
 +
|-
 +
| class="field" |
 +
; address_id
 +
| The internal address ID used by a jurisdictions master address repository or other addressing system.  
 +
|
 +
|-
 +
| class="field" |
 +
; zipcode
 +
| The postal code for the location of the service request.
 +
|
 +
|-
 +
| class="field" |
 +
; lat
 +
| latitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
 +
|
 +
|-
 +
| class="field" |
 +
; long
 +
| longitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
 +
|
 +
|-
 +
| class="field" |
 +
; media_url
 +
| A URL to media associated with the request, eg an image.  
 +
| A convention for parsing media from this URL has yet to be established, so currently it will be done on a case by case basis much like Twitter.com does. For example, if a jurisdiction accepts photos submitted via Twitpic.com, then clients can parse the page at the Twitpic URL for the image given the conventions of Twitpic.com. This could also be a URL to a media RSS feed where the clients can parse for media in a more structured way.
 +
|}
 +
 
  
 
====Possible Errors====
 
====Possible Errors====
Line 826: Line 1,201:
  
 
====Response====
 
====Response====
−
* '''errors'''
+
{| class="spec-table" class="spec-table"
−
** Explanation: root element
+
! Field Name
−
* '''error'''
+
! class="spec-description"|Description
−
** Parent: errors
+
! class="spec-requirements"| Notes & Requirements
−
** Explanation: container for code, description
+
|-
−
* '''code'''
+
!colspan="3" class="response-container"|errors ⇊
−
** Parent: error
+
|-
−
** Explanation: The error code representing the type of error. In most cases, this should match the HTTP status code returned in the HTTP header.
+
!colspan="3" class="response-container"|error ↴
−
* '''description'''
+
|-
−
** Parent: error
+
| class="field" |
−
** Explanation: A human readable description of the error that occurred. This is meant to be seen by the user.  
+
; code
−
 
+
| The error code representing the type of error. In most cases, this should match the HTTP status code returned in the HTTP header.
 +
|
 +
|-
 +
| class="field" |
 +
; description
 +
| A human readable description of the error that occurred. This is meant to be seen by the user.  
 +
|
 +
|}
  
 
* '''General Errors'''
 
* '''General Errors'''

Latest revision as of 11:34, 11 October 2012

This spec has been frozen and finalized, but the documentation will continue to be updated for clarity. Join the Mailing List for updates.

The GeoReport API v2 allows developers to build applications to both view and report issues which government entities like cities are responsible for addressing. These interactions are often referred to as "service requests" or "calls for service" and have traditionally been handled by custom web forms or phone based call centers (sometimes using the 311 phone number or other short-code). The GeoReport API is designed to allow both government and third party developers to create new applications and technologies that can integrate directly with these same official contact centers in any government that supports the standard. The current specification is focused on location-based non-emergency issues such as graffiti, potholes, and street cleaning.

The API consists of two main kinds of resources: services and service requests, but some servers that can't generate a realtime service request may also rely on a token resource. In total there are six methods used to interact with these resources: GET services, GET a service definition (a specific service_code id), POST a request, GET requests, GET a request (a specific service_request_id). The documentation below (starting from the API Methods section) is ordered based on a common sequence of interactions where a person first sees a list of available service types, selects one and creates a new service request, and then is able to track the status of that request and other requests. However each method can be accessed independently and some applications may only be focused on querying existing service requests to do analytics.

Status

Specification

Stable: The GeoReport v2 Spec has been finalized, but we are still updating documentation for clarity and verifying compliance of implementations

Servers

Servers receive and manage service requests on behalf of a jurisdiction. A comprehensive list is being maintained on the GeoReport v2 Servers page


Apps & Resources

Service Discovery

GeoReport v2 and subsequent Open311 APIs are also required to have a standard service discovery file associated with them to provide routing between versions and types of APIs. See the Service Discovery page for details of the specification.

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. Examples of the HTTP content-type headers for each format are shown below under Format Support.

Format Support

XML is a required format, but JSON can be provided at the discretion of the API provider. The output formats supported by the provider are indicated through the Service Discovery formats field for the API endpoint being used. The client can specify the desired format by appending the format name to the resource. For example a GET request to /services.xml for text/xml output from the services resource and /services/01.json for application/json (RFC 4627) output for a specific service definition.

The HTTP content-type headers should look like this for each format:

POST Service Request: Content-Type: application/x-www-form-urlencoded; charset=utf-8

XML: Content-Type: text/xml; charset=utf-8

JSON: Content-Type: application/json; charset=utf-8

XML Support

XML for the API should be Content-Type: text/xml. The XML output currently defined is schemaless and without a namespace declaration. For now, extending the output with additional namespaces should be done at your own risk. To guarantee that all clients can support the XML output, it is recommended that you adhere to the specification strictly and do not include foreign tags or namespaces. It is also assumed that the default namespace is not specified, but if it must be specified, the XMLNS URI is the URL of the specification: http://wiki.open311.org/GeoReport_v2

JSON Support

JSON for the API should be Content-Type: application/json. JSON support is based on a programmatic mapping of the XML format using the Spark Convention. This means that if you have an XML file, you can easily generate the JSON version with XSL. This can be done using a server side XSLT (php example).

Definitions

jurisdiction_id

As a means to allow this API to distinguish multiple jurisdictions within one API endpoint 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

Purpose provide a list of acceptable 311 service request types and their associated service codes. These request types can be unique to the city/jurisdiction.
URL https://[API endpoint]/services.[format]
Sample URL https://api.city.gov/dev/v2/services.xml?jurisdiction_id=city.gov
Formats XML (JSON available if denoted by Service Discovery)
HTTP Method GET
Requires API Key No


Required Arguments

Field Name Description Notes & Requirements
jurisdiction_id
This is only required if the endpoint serves multiple jurisdictions

Response

Field Name Description Notes & Requirements
services ⇊
service ↴
service_code
The unique identifier for the service request type
service_name
The human readable name of the service request type
description
A brief description of the service request type.
metadata
Determines whether there are additional form fields for this service type.
  • 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.
Possible values: true, false.
type
  • 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
Possible values: realtime, batch, blackbox.
keywords
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
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


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. These attributes can be unique to the city/jurisdiction.
URL https://[API endpoint]/services/[service_code].[format]
Sample URL https://api.city.gov/dev/v2/services/033.xml?jurisdiction_id=city.gov
Formats XML (JSON available if denoted by Service Discovery)
HTTP Method GET
Requires API Key No


Required Arguments

Field Name Description Notes & Requirements
jurisdiction_id
This is only required if the endpoint serves multiple jurisdictions
service_code
The service_code is specified in the main URL path rather than an added query string parameter.


Response

Field Name Description Notes & Requirements
service_definition ↴
service_code
Returns the service_code associated with the definition, the same one submitted for this call.
attributes ⇊
attribute ↴
variable
  • true denotes that user input is needed
  • false means the attribute is only used to present information to the user within the description field
Possible values: true, false.
code
A unique identifier for the attribute
datatype
Denotes the type of field used for user input.
  • string: A string of characters without line breaks. Represented in an HTML form using an <input> tag
  • number: A numeric value. Represented in an HTML form using an <input> tag
  • datetime: The input generated must be able to transform into a valid ISO 8601 date. Represented in an HTML form using <input> tags
  • text: A string of characters that may contain line breaks. Represented in an HTML form 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 form 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 form using the <select multiple="multiple"> and <option> tags
Options: string, number, datetime, text, singlevaluelist, multivaluelist.
required
  • true means that the value is required to submit service request
  • false means that the value not required.
Options: true, false.
datatype_description
A description of the datatype which helps the user provide their input
order
The sort order that the attributes will be presented to the user. 1 is shown first in the list. Any positive integer not used for other attributes in the same service_code
description
An description of the attribute field with instructions for the user to find and identify the requested information
values ⇊
value ↴
key
The unique identifier associated with an option for singlevaluelist or multivaluelist. This is analogous to the value attribute in an html option tag.
name
The human readable title of an option for singlevaluelist or multivaluelist. This is analogous to the innerhtml text node of an html option tag.


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


POST Service Request

Purpose Create service requests
URL https://[API endpoint]/requests.[format]
Sample URL https://api.city.gov/dev/v2/requests.xml
Format sent Content-Type: application/x-www-form-urlencoded
Formats returned XML (JSON available if denoted by Service Discovery)
HTTP Method POST
Requires API Key Yes


Required Arguments

Field Name Description Notes & Requirements
jurisdiction_id
This is only required if the endpoint serves multiple jurisdictions
service_code
This is obtained from GET Service List method
location parameter
A full location parameter must be submitted. One of lat & long or address_string or address_id
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 as well as multiple values for the same code in the case of a multivaluelist datatype (attribute[code1][]=value1&attribute[code1][]=value2&attribute[code1][]=value3) - see example.
This is only required if the service_code requires a service definition with required fields.


Optional Arguments

Field Name Description Notes & Requirements
lat
Latitude using the (WGS84) projection. lat & long both need to be sent even though they are sent as two separate parameters. lat & long are required if no address_string or address_id is provided.
long
Longitude using the (WGS84) projection. lat & long both need to be sent even though they are sent as two separate parameters. lat & long are required if no address_string or address_id is provided.
address_string
Human entered address or description of location. This is required if no lat/long or address_id are provided. 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.
address_id
The internal address ID used by a jurisdiction's master address repository or other addressing system. This is required if no lat/long or address_string are provided.
email
The email address of the person submitting the request
device_id
The unique device ID of the device submitting the request. This is usually only used for mobile devices. Android devices can use TelephonyManager.getDeviceId() and iPhones can use [UIDevice currentDevice].uniqueIdentifier
account_id
The unique ID for the user account of the person submitting the request
first_name
The given name of the person submitting the request
last_name
The family name of the person submitting the request
phone
The phone number of the person submitting the request
description
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
A URL to media associated with the request, eg an image. A convention for parsing media from this URL has yet to be established, so currently it will be done on a case by case basis much like Twitter.com does. For example, if a jurisdiction accepts photos submitted via Twitpic.com, then clients can parse the page at the Twitpic URL for the image given the conventions of Twitpic.com. This could also be a URL to a media RSS feed where the clients can parse for media in a more structured way.


Response

Field Name Description Notes & Requirements
service_requests ⇊
request ↴
service_request_id
The unique ID of the service request created. This should not be returned if token is returned
token
If returned, use this to call GET service_request_id from a token. This should not be returned if service_request_id is returned
service_notice
Information about the action expected to fulfill the request or otherwise address the information reported. May not be returned
account_id
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: api.city.gov
Content-Type: application/x-www-form-urlencoded; charset=utf-8

api_key=xyz&jurisdiction_id=city.gov&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:


GET service_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 service_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://api.city.gov/dev/v2/tokens/123456.xml?jurisdiction_id=city.gov
Formats XML (JSON available if denoted by Service Discovery)
HTTP Method GET
Requires API Key No


Required Arguments

Field Name Description Notes & Requirements
jurisdiction_id
This is only required if the endpoint serves multiple jurisdictions
token
This is obtained from the POST Service Requests method


Response

Field Name Description Notes & Requirements
service_requests ⇊
request ↴
service_request_id
The unique ID for the service request created. This can be used to call the GET Service Request method.
token
The token ID used to make this call.


Possible Errors

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

  • 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


GET Service Requests

Purpose Query the current status of multiple requests
URL https://[API endpoint]/requests.[format]
Sample URL https://api.city.gov/dev/v2/requests.xml?start_date=2010-05-24T00:00:00Z&end_date=2010-06-24T00:00:00Z&status=open&jurisdiction_id=city.gov
Formats XML (JSON available if denoted by Service Discovery)
HTTP Method GET
Requires API Key No


Required Arguments

Field Name Description Notes & Requirements
jurisdiction_id
This is only required if the endpoint serves multiple jurisdictions

Optional Arguments

Field Name Description Notes & Requirements
service_request_id
To call multiple Service Requests at once, multiple service_request_id can be declared; comma delimited. This overrides all other arguments.
service_code
Specify the service type by calling the unique ID of the service_code. This defaults to all service codes when not declared; can be declared multiple times, comma delimited
start_date
Earliest datetime to include in search. When provided with end_date, allows one to search for requests which have a requested_datetime that matches a given range, but may not span more than 90 days. When not specified, the range defaults to most recent 90 days. Must use w3 format, eg 2010-01-01T00:00:00Z.
end_date
Latest datetime to include in search. When provided with start_date, allows one to search for requests which have a requested_datetime that matches a given range, but may not span more than 90 days. When not specified, the range defaults to most recent 90 days. Must use w3 format, eg 2010-01-01T00:00:00Z.
status
Allows one to search for requests which have a specific status. This defaults to all statuses; can be declared multiple times, comma delimited; Options: open, closed

Response

Field Name Description Notes & Requirements
service_requests ⇊
request ↴
service_request_id
The unique ID of the service request created.
status
The current status of the service request.
  • open: it has been reported.
  • closed: it has been resolved.
Options: open, closed
status_notes
Explanation of why status was changed to current state or more details on current status than conveyed with status alone. May not be returned
service_name
The human readable name of the service request type
service_code
The unique identifier for the service request type
description
A full description of the request or report submitted. This may contain line breaks, but not html or code. Otherwise, this is free form text limited to 4,000 characters.
agency_responsible
The agency responsible for fulfilling or otherwise addressing the service request. May not be returned
service_notice
Information about the action expected to fulfill the request or otherwise address the information reported. May not be returned
requested_datetime
The date and time when the service request was made. Returned in w3 format, eg 2010-01-01T00:00:00Z
updated_datetime
The date and time when the service request was last modified. For requests with status=closed, this will be the date the request was closed. Returned in w3 format, eg 2010-01-01T00:00:00Z
expected_datetime
The date and time when the service request can be expected to be fulfilled. This may be based on a service-specific service level agreement. May not be returned
address
Human readable address or description of location. This should be provided from most specific to most general geographic unit, eg address number or cross streets, street name, neighborhood/district, city/town/village, county, postal code.
address_id
The internal address ID used by a jurisdictions master address repository or other addressing system.
zipcode
The postal code for the location of the service request.
lat
latitude using the (WGS84) projection.
long
longitude using the (WGS84) projection.
media_url
A URL to media associated with the request, eg an image. A convention for parsing media from this URL has yet to be established, so currently it will be done on a case by case basis much like Twitter.com does. For example, if a jurisdiction accepts photos submitted via Twitpic.com, then clients can parse the page at the Twitpic URL for the image given the conventions of Twitpic.com. This could also be a URL to a media RSS feed where the clients can parse for media in a more structured way.


Response Volume

  • Default query limit is a span of 90 days or first 1000 requests returned, whichever is smallest.

Possible Errors

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

  • 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


GET Service Request

Purpose Query the current status of an individual request
URL https://[API endpoint]/requests/[service_request_id].[format]
Sample URL https://api.city.gov/dev/v2/requests/123456.xml?jurisdiction_id=city.gov
Formats XML (JSON available if denoted by Service Discovery)
HTTP Method GET
Requires API Key No


Required Arguments

Field Name Description Notes & Requirements
jurisdiction_id
This is only required if the endpoint serves multiple jurisdictions
service_request_id
The service_request_id is specified in the main URL path rather than an added query string parameter.


Optional Arguments

None

Response

Field Name Description Notes & Requirements
service_requests ⇊
request ↴
service_request_id
The unique ID of the service request created.
status
The current status of the service request.
  • open: it has been reported.
  • closed: it has been resolved.
Options: open, closed
status_notes
Explanation of why status was changed to current state or more details on current status than conveyed with status alone. May not be returned
service_name
The human readable name of the service request type
service_code
The unique identifier for the service request type
description
A full description of the request or report submitted. This may contain line breaks, but not html or code. Otherwise, this is free form text limited to 4,000 characters.
agency_responsible
The agency responsible for fulfilling or otherwise addressing the service request. May not be returned
service_notice
Information about the action expected to fulfill the request or otherwise address the information reported. May not be returned
requested_datetime
The date and time when the service request was made. Returned in w3 format, eg 2010-01-01T00:00:00Z
updated_datetime
The date and time when the service request was last modified. For requests with status=closed, this will be the date the request was closed. Returned in w3 format, eg 2010-01-01T00:00:00Z
expected_datetime
The date and time when the service request can be expected to be fulfilled. This may be based on a service-specific service level agreement. May not be returned
address
Human readable address or description of location. This should be provided from most specific to most general geographic unit, eg address number or cross streets, street name, neighborhood/district, city/town/village, county, postal code.
address_id
The internal address ID used by a jurisdictions master address repository or other addressing system.
zipcode
The postal code for the location of the service request.
lat
latitude using the (WGS84) projection.
long
longitude using the (WGS84) projection.
media_url
A URL to media associated with the request, eg an image. A convention for parsing media from this URL has yet to be established, so currently it will be done on a case by case basis much like Twitter.com does. For example, if a jurisdiction accepts photos submitted via Twitpic.com, then clients can parse the page at the Twitpic URL for the image given the conventions of Twitpic.com. This could also be a URL to a media RSS feed where the clients can parse for media in a more structured way.


Possible Errors

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

  • 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


Errors

Response

Field Name Description Notes & Requirements
errors ⇊
error ↴
code
The error code representing the type of error. In most cases, this should match the HTTP status code returned in the HTTP header.
description
A human readable description of the error that occurred. This is meant to be seen by the user.
  • 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


HTTP error codes are required, but the code in the response body shouldn't necessarily match the HTTP error code, so that more specific and unique error code identifiers can be used. The HTTP error codes should always be 404 for resources that don't exist, 403 for errors because of wrong or missing api_key and basically 400 for any other error where the request can not be fulfilled as expected. Multiple errors codes and descriptions can be returned in the body (the response is an array).

Example:

Retrieved from "https://wiki-archive.open311.org/index.php?title=GeoReport_v2&oldid=1431"