Difference between revisions of "GeoReport v2.1 Draft"

Latest revision as of 15:21, 25 September 2012

This is a fork of the GeoReport v2 spec documentation for use in drafting a v2.1 version of the spec. Use the Mailing List for discussion.

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.

Status

Specification

In Development: The GeoReport v2.1 Spec is currently being drafted

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 their 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

<?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>
</services>

[
  {
    "service_code":001,
    "service_name":"Cans left out 24x7",
    "description":"Garbage or recycling cans that have been left out for more than 24 hours after collection. Violators will be cited.",
    "metadata":true,
    "type":"realtime",
    "keywords":"lorem, ipsum, dolor",
    "group":"sanitation"
  },
  {
    "service_code":002,
    "metadata":true,
    "type":"realtime",
    "keywords":"lorem, ipsum, dolor",
    "group":"street",
    "service_name":"Construction plate shifted",
    "description":"Metal construction plate covering the street or sidewalk has been moved."
  },
  {
    "service_code":003,
    "metadata":true,
    "type":"realtime",
    "keywords":"lorem, ipsum, dolor",
    "group":"street",
    "service_name":"Curb or curb ramp defect",
    "description":"Sidewalk curb or ramp has problems such as cracking, missing pieces, holes, and/or chipped curb."
  }
]

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 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	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.
media	An array of file uploads	A client may POST multiple files as multipart/form-data. This is the equivalent of having multiple <input type="file" name="media[]" /> inputs. Subsequent calls for GET Service Requests should return the URL for this file via the media_urls field. This means that a client can not simultaneously post a URL for media_url and post files via media. If this is done, the files uploaded via the media field will take precedence and be returned as URLs in the media_url field.

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 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 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://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 requested_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 requested_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.
updated_after	Earliest updated_datetime to include in search. Allows one to search for requests which have an updated_datetime between the updated_after time and updated_before time (or now). This is useful for downloading a changeset that includes changes to older requests or to just query very recent changes.	Must use w3 format, eg 2010-01-01T00:00:00Z.
updated_before	Latest updated_datetime to include in search. Allows one to search for requests which have an updated_datetime between the updated_after time and the updated_before time. This is useful for downloading a changeset that includes changes to older requests or to just query very recent changes.	When not specified (updated_after is used without updated_before) then updated_before is assumed to be now. Must use w3 format, eg 2010-01-01T00:00:00Z. TODO: what happens when used without updated_after? Set a default range or range limit like start_date & end_date?
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

<?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://city.gov.s3.amazonaws.com/requests/media/638344.jpg </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://city.gov.s3.amazonaws.com/requests/media/638349.jpg </media_url>
	</request>
</service_requests>

[
  {
    "service_request_id":638344,
    "status":"closed",
    "status_notes":"Duplicate request.",
    "service_name":"Sidewalk and Curb Issues",
    "service_code":006,
    "description":null,
    "agency_responsible":null,
    "service_notice":null,
    "requested_datetime":"2010-04-14T06:37:38-08:00",
    "updated_datetime":"2010-04-14T06:37:38-08:00",
    "expected_datetime":"2010-04-15T06:37:38-08:00",
    "address":"8TH AVE and JUDAH ST",
    "address_id":545483,
    "zipcode":94122,
    "lat":37.762221815,
    "long":-122.4651145,
    "media_url":"http://city.gov.s3.amazonaws.com/requests/media/638344.jpg "
  },
  {
    "service_request_id":638349,
    "status":"open",
    "status_notes":null,
    "service_name":"Sidewalk and Curb Issues",
    "service_code":006,
    "description":null,
    "agency_responsible":null,
    "service_notice":null,
    "requested_datetime":"2010-04-19T06:37:38-08:00",
    "updated_datetime":"2010-04-19T06:37:38-08:00",
    "expected_datetime":"2010-04-19T06:37:38-08:00",
    "address":"8TH AVE and JUDAH ST",
    "address_id":545483,
    "zipcode":94122,
    "lat":37.762221815,
    "long":-122.4651145,
    "media_url":"http://city.gov.s3.amazonaws.com/requests/media/638349.jpg"
  }
]

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:

@@ Line 1: / Line 1: @@
+ This is a fork of the GeoReport v2 spec documentation for use in drafting a v2.1 version of the spec. Use the [http://lists.open311.org/groups/discuss Mailing List] for discussion.
 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.
+==Status==
+===Specification===
+<span style="color:red;font-weight:bold">In Development:</span> The GeoReport v2.1 Spec is currently being drafted
+==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==
@@ Line 14: / Line 24: @@
 UTF-8 is required everywhere.
-All text returned by the service, whether in XML, JSON, or any other text-based content-type, MUST be encoded as UTF-8. Appropriate HTTP headers must be set, and the XML root element must contain the appropriate encoding="UTF-8" attribute. All text received by the service from the client will be assumed to be UTF-8 and must be decoded accordingly.
+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 ([http://www.ietf.org/rfc/rfc4627.txt 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 [http://wiki.open311.org/JSON_and_XML_Conversion#The_Spark_Convention 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 ([http://sandbox.georeport.org/tools/sparkjson/xml2json_spark_php.txt php example]).
 ==Definitions==
-===jurisdiction_id===
+====jurisdiction_id====
-As a means to allow this API to be used by multiple cities we've included a "jurisdiction_id" which will be the unique identifier for cities. It has been suggested that we use the city's url as the "jurisdiction_id". We have incorporated that suggestion into our design and the jurisdiction_id for San Francisco = sfgov.org
+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 services and associated service code
+{| class="spec-table" class="method-table"
-* '''URL:'''https://open311.sfgov.org/dev/v2/services.[format]
+!scope="row" | Purpose
-*'''Sample URL:''' https://open311.sfgov.org/dev/v2/services.xml?api_key=xyz&jurisdiction_id=sfgov.org
+| 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
+|-
-*'''HTTP Method: '''GET
+!scope="row" | URL
-*'''Requires API Key: '''No
+| https://[API endpoint]/services.[format]
-*'''Arguments: '''
+|-
-** jurisdiction_id (for SF = sfgov.org)
+!scope="row" | Sample URL
-*'''Response:'''
+|  <nowiki>https://api.city.gov/dev/v2/services.xml?jurisdiction_id=city.gov</nowiki>
-** name (was service_name)
+|-
-** code (was service_code)
+!scope="row" | Formats
-** description (was service_description)
+|  XML (JSON available if denoted by [[Service Discovery]])
-** group (to let developers group similar request types) - may be blank
+|-
-** keywords (to allow for associations with similar words) - may be blank
+!scope="row" | HTTP Method
-** metadata (true = need to make service_defintion call, false = do not make service_definition call)
+| GET
-** type (realtime = service request ID returned immediately, batch = token will be returned, blackbox = no tracking of service requests)
+|-
+!scope="row" | Requires API Key
+| No
+|}
-'''Example response:'''
-<pre class="brush:xml">
+====Required Arguments====
+{| 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====
+{| class="spec-table"
+! Field Name
+! class="spec-description"|Description
+! class="spec-requirements"| Notes & Requirements
+|-
+!colspan="3" class="response-container"|services ⇊
+|-
+!colspan="3" class="response-container"|service ↴
+|-
+| class="field" |
+; service_code
+| The unique identifier for the service request type
+|
+|-
+| class="field" |
+; service_name
+| The human readable name of the service request type
+|
+|-
+| class="field" |
+;  description
+| A brief description of the service request type.
+|
+|-
+| class="field" |
+; metadata
+| Determines whether their are additional form fields for this service type.
+* <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.
+* <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.
+| Possible values: <span class="strict-value">true</span>, <span class="strict-value">false</span>.
+|-
+| 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====
+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====
+<tabs>
+<tab title="XML">
+<pre class="brush:xml">
+<?xml version="1.0" encoding="utf-8"?>
 <services>
-		<service code="001" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sanitation" name="Cans left out 24x7" description="Garbage or recycling cans that have been left out for more than 24 hours after collection. Violators will be cited. "/>
+	<service>
-		<service code="002" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="street" name="Construction plate shifted" description="Metal construction plate covering the street or sidewalk has been moved. "/>
+		<service_code>001</service_code>
-		<service code="003" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="street" name="Curb or curb ramp defect" description="Sidewalk curb or ramp has problems such as cracking, missing pieces, holes, and/or chipped curb. "/>
+		<service_name>Cans left out 24x7</service_name>
-		<service code="004" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sanitation" name="Damaged city can" description="Damage to a city garbage receptacle such as missing parts (lid, door, liner) or other physical damage. "/>
+		<description>Garbage or recycling cans that have been left out for more than 24 hours after collection. Violators will be cited.</description>
-		<service code="005" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sewer" name="Damaged side sewer vent cover" description="Damage to a side sewer vent cover with problems such as cracking, bending, rusting, or denting"/>
+		<metadata>true</metadata>
-		<service code="006" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="tree" name="Damaged tree" description="Damage to a city maintained tree. To check whether a tree is city maintained: http://bit.ly/6hsDk1"/>
+		<type>realtime</type>
-		<service code="007" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="graffiti" name="Graffiti on bike rack - not offensive" description="Graffiti on a bike rack that does not contain racial slurs, profanity, or gang related language"/>
+		<keywords>lorem, ipsum, dolor</keywords>
-		<service code="008" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="graffiti" name="Graffiti on news rack - not offensive" description="Graffiti on a news rack that does not contain racial slurs, profanity, or gang related language "/>
+		<group>sanitation</group>
-		<service code="009" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="graffiti" name="Graffiti on parking meter - not offensive" description="Graffiti on a parking meter that does not contain racial slurs, profanity, or gang related language "/>
+	</service>
-		<service code="010" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="graffiti" name="Graffiti on pay phone - not offensive" description="Graffiti on a pay phone that does not contain racial slurs, profanity, or gang related language.  "/>
+	<service>
-		<service code="011" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="graffiti" name="Graffiti on private property - not offensive" description="Graffiti on a privately owned building or structure that does not contain racial slurs, profanity, or gang related language  "/>
+		<service_code>002</service_code>
-		<service code="012" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="graffiti" name="Graffiti on private property - offensive" description="Graffiti on a privately owned building or structure that contains racial slurs, profanity, or gang related language "/>
+		<metadata>true</metadata>
-		<service code="013" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="graffiti" name="Graffiti on public property - offensive" description="Graffiti on public property (building, pole, sidewalk, hydrant, etc) with racial slurs, profanity, or gang related language "/>
+		<type>realtime</type>
-		<service code="014" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="graffiti" name="Graffiti on public property- not offensive" description="Graffiti on public property (building, pole, sidewalk, hydrant, etc) without racial slurs, profanity, or gang related language  "/>
+		<keywords>lorem, ipsum, dolor</keywords>
-		<service code="015" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sanitation" name="Illegal dumping" description="Identify someone that has dumped or is dumping furniture or garbage onto the street or sidewalk. Violators will be cited "/>
+		<group>street</group>
-		<service code="016" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="landscaping" name="Landscaping request" description="Request maintenance on public property (except on park property) such as lawn mowing, bush or strip trimming and removal "/>
+		<service_name>Construction plate shifted</service_name>
-		<service code="017" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="street" name="Missed route - mechanical sweeping" description="Street cleaning sweeper did not show up as scheduled according to the street cleaning signs "/>
+		<description>Metal construction plate covering the street or sidewalk has been moved.</description>
-		<service code="018" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sewer" name="Missing side sewer vent cover" description="The 4 side sewer vent cover (http://bit.ly/57BlOv) is missing from the sidewalk  "/>
+	</service>
-		<service code="019" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sanitation" name="Overflowing city receptacle or dumpster" description="City receptacle is overflowing and/or has garbage on and around the container "/>
+	<service>
-		<service code="020" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="tree" name="Overgrown tree" 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 "/>
+		<service_code>003</service_code>
-		<service code="021" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="street" name="Pothole in Street" description="Defect on the street such as broken, cracked, and sinking asphalt or concrete "/>
+		<metadata>true</metadata>
-		<service code="022" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sewer" name="Sewage coming out of catch basin" description="Sewage or dirty water coming out of a catchbasin (located at the corner of intersections) "/>
+		<type>realtime</type>
-		<service code="023" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sewer" name="Water coming from side sewer" description="Sewage or odor coming out of a 4 side sewer (http://bit.ly/57BlOv) located on the sidewalk "/>
+		<keywords>lorem, ipsum, dolor</keywords>
-		<service code="024" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sidewalk" name="Sidewalk cleaning" description="Have garbage or human waste removed from the sidewalk and/or request services such as steam cleaning of sidewalks "/>
+		<group>street</group>
-		<service code="025" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sidewalk" name="Sidewalk defect" description="Defect on the sidewalk such as broken, cracked, and/or sinking concrete "/>
+		<service_name>Curb or curb ramp defect</service_name>
-		<service code="026" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group=street"" name="Street cleaning" description="Request to have garbage or human waste removed from the street "/>
+		<description>Sidewalk curb or ramp has problems such as cracking, missing pieces, holes, and/or chipped curb.</description>
-		<service code="027" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="tree" name="Tree damaging property" 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 "/>
+	</service>
-		<service code="028" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="water main" name="Water main break" description="Street is flooding due to water coming from within the asphalt or from a catchbasin "/>
-		<service code="029" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="graffiti" name="Graffiti on street sign" description="Graffiti on a street sign such as a stop sign, street name, and/or other parking and traffic signs "/>
-		<service code="030" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sewer" name="Odor coming from Side Sewer" description="Odor coming out of a 4 side sewer (http://bit.ly/57BlOv) located on the sidewalk.  "/>
-		<service code="031" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sewer" name="Sewage coming out of manhole cover" description="Sewage or dirty water coming out of a manhole cover (typically located in the a street or alley) "/>
-		<service code="032" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="sewer" name="Sewage coming out of sewer vent" description="Sewage or dirty water coming out of a sewer vent (located on the sidewalk) "/>
-		<service code="033" metadata="true" type="realtime" keywords="lorem, ipsum, dolor" group="street" name="Pothole in bike lane" description="Defect in the bike lane such as broken, cracked, and sinking asphalt or concrete. "/>
 </services>
+</pre>
+</tab>
+<tab title="JSON">
+<pre class="brush:js">
+[
+  {
+    "service_code":001,
+    "service_name":"Cans left out 24x7",
+    "description":"Garbage or recycling cans that have been left out for more than 24 hours after collection. Violators will be cited.",
+    "metadata":true,
+    "type":"realtime",
+    "keywords":"lorem, ipsum, dolor",
+    "group":"sanitation"
+  },
+  {
+    "service_code":002,
+    "metadata":true,
+    "type":"realtime",
+    "keywords":"lorem, ipsum, dolor",
+    "group":"street",
+    "service_name":"Construction plate shifted",
+    "description":"Metal construction plate covering the street or sidewalk has been moved."
+  },
+  {
+    "service_code":003,
+    "metadata":true,
+    "type":"realtime",
+    "keywords":"lorem, ipsum, dolor",
+    "group":"street",
+    "service_name":"Curb or curb ramp defect",
+    "description":"Sidewalk curb or ramp has problems such as cracking, missing pieces, holes, and/or chipped curb."
+  }
+]
 </pre>
+</tab>
+</tabs>
 ===GET Service Definition===
-*'''Purpose:''' define attributes associated with a service code
+{| class="spec-table" class="method-table"
-*'''URL:''' https://open311.sfgov.org/dev/v2/services/033.[format]
+!scope="row" | Conditional
-*'''Sample URL:'''https://open311.sfgov.org/dev/v2/service_definition.xml?api_key=xyz&service_code=DMV66
+| 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>
-*'''Formats:''' xml
+|-
-*'''HTTP Method:''' GET
+!scope="row" | Purpose
-*'''Requires API Key:''' No
+| Define attributes associated with a service code. These attributes can be unique to the city/jurisdiction.
+|-
+!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
+|}
-* Arguments:
-** service_code
-* Response:
+====Required Arguments====
-**variable
+{| class="spec-table arguments-table"
-**code
+! Field Name
-**datatype (options: string, number, datetime, text, singlevaluelist, multivaluelist)
+! class="spec-description"|Description
-**required (value is required to submit service request)
+! class="spec-requirements"| Notes & Requirements
-**datatype_description
+|-
-**order
+| class="field" |
-**description
+; jurisdiction_id
-**service_code
+|
-**values (optional, provides list of values in comma separated format for singlevaluelist and multivaluelist)
+| <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.
+|}
-'''Example response:'''
+====Response====
+{| class="spec-table"
+! Field Name
+! class="spec-description"|Description
+! class="spec-requirements"| Notes & Requirements
+|-
+!colspan="3" class="response-container"|service_definition ↴
+|-
+| class="field" |
+; service_code
+| Returns the service_code associated with the definition, the same one submitted for this call.
+|
+|-
+!colspan="3" class="response-container"|attributes ⇊
+|-
+!colspan="3" class="response-container"|attribute ↴
+|-
+| class="field" |
+; variable
+|
+* <span class="strict-value">true</span> denotes that user input is needed
+* <span class="strict-value">false</span> means the attribute is only used to present information to the user within the description field
+| Possible values: <span class="strict-value">true</span>, <span class="strict-value">false</span>.
+|-
+| class="field" |
+;  code
+| A unique identifier for the attribute
+|
+|-
+| class="field" |
+; datatype
+| Denotes the type of field used for user input.
+* <span class="strict-value">string</span>: A string of characters without line breaks. Represented in an HTML from using an <input> tag
+* <span class="strict-value">number</span>: A numeric value. Represented in an HTML from using an <input> tag
+* <span class="strict-value">datetime</span>: The input generated must be able to transform into a valid ISO 8601 date. Represented in an HTML from using <input> tags
+* <span class="strict-value">text</span>:  A string of characters that may contain line breaks. Represented in an HTML from using an <textarea> tag
+* <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 from using the <select> and <option> tags
+* <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 from using the <select multiple="multiple"> and <option> tags
+| 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>.
+|-
+| class="field" |
+; required
+|
+* <span class="strict-value">true</span> means that the value is required to submit service request
+* <span class="strict-value">false</span> means that the value not required.
+| Options: <span class="strict-value">true</span>, <span class="strict-value">false</span>.
+|-
+| class="field" |
+; datatype_description
+| A description of the datatype which helps the user provide their input
+|
+|-
+| class="field" |
+; 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.
+|
+|}
+====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====
+<tabs>
+<tab title="XML">
 <pre class="brush:xml">
-	<service_definition>
+<?xml version="1.0" encoding="utf-8"?>
+<service_definition>
+	<service_code>DMV66</service_code>
+	<attributes>
 		<attribute>
 			<variable>true</variable>
 			<code>WHISHETN</code>
-			<datatype>select_single</datatype>
+			<datatype>singlevaluelist</datatype>
 			<required>true</required>
 			<datatype_description></datatype_description>
@@ Line 119: / Line 369: @@
 			<description>What is the ticket/tag/DL number?</description>
 			<values>
-			    <value key="123" name="label" />
+				<value>
-				<value key="123" name="label" />
+					<key>123</key>
+					<name>Ford</name>
+				</value>
+				<value>
+					<key>124</key>
+					<name>Chrysler</name>
+				</value>
 			</values>
-		<attribute>
+		</attribute>
-		<service_code>DMV66</service_code>
+	</attributes>
-	</service_definition>
+</service_definition>
 </pre>
+</tab>
+<tab title="JSON">
+<pre class="brush:js">
+{
+  "service_code":"DMV66",
+  "attributes":[
+    {
+      "variable":true,
+      "code":"WHISHETN",
+      "datatype":"singlevaluelist",
+      "required":true,
+      "datatype_description":null,
+      "order":1,
+      "description":"What is the ticket/tag/DL number?",
+      "values":[
+        {
+          "key":123,
+          "name":"Ford"
+        },
+        {
+          "key":124,
+          "name":"Chrysler"
+        }
+      ]
+    }
+  ]
+}
+</pre>
+</tab>
+</tabs>
 ===POST Service Request===
-*'''Purpose:''' Create service requests
+{| class="spec-table" class="method-table"
-*'''URL:''' https://open311.sfgov.org/dev/v2/requests.[format]
+!scope="row" | Purpose
-*'''Sample URL:'''https://open311.sfgov.org/dev/v2/requests.xml?api_key=xyz&jurisdiction_id=sfgov.org&service_code=001&lat=37.76524078&long=-122.4212043&address_string=xxxx6thstreet&customer_email=smit333@sfgov.edu&device_id=tt222111&account_id=&first_name=jo&last_name=smith&phone_number=111111111&description=&media_url=http://okgogo.gogo
+| Create service requests
-*'''Formats:''' xml
+|-
-*'''HTTP Method:''' POST
+!scope="row" | URL
-*'''Requires API Key:''' Yes
+| https://[API endpoint]/requests.[format]
-*'''Required Arguments:'''
+|-
-** api_key
+!scope="row" | Sample URL
-** jurisdiction_id
+|  <nowiki>https://api.city.gov/dev/v2/requests.xml</nowiki>
-** service_code (obtained from method service_list)
+|-
-***
+!scope="row" | Format sent
-*'''Optional Arguments:'''
+|  Content-Type: application/x-www-form-urlencoded
-** lat [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] (required - either lat/lon or address string, both are preferred)
+|-
-** long [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] (required - either lat/lon or address string, both are preferred)
+!scope="row" | Formats returned
-** address_string (human entered description of location)(if no lat/lon must provide this information)
+|  XML (JSON available if denoted by [[Service Discovery]])
-** address_id - ID in Master Address Repository
+|-
-** email
+!scope="row" | HTTP Method
-** device_id
+| POST
-** account_id
+|-
-** first_name
+!scope="row" | Requires API Key
-** last_name
+| Yes
-** phone
+|}
-** description (free form limited to 4,000 characters)
-** media_url (URL of a jpeg image)
-** source_url (URL of original report, eg from SeeClickFix - http://www.seeclickfix.com/issues/8060)
-*'''Response: '''
-** service_request_id (may not be returned if token is returned)
-** token (if returned then use token method)
-** service_notice (may not be returned)
-** account_id (may not be returned)
-** error codes
-'''About Responses '''
+====Required Arguments====
-There are three response types: realtime, asynchronous, and other. A realtime response will return a service_request_id, an asynchronous response
+{| class="spec-table arguments-table"
-will return a token, and if neither is returned an explanation will be provided in the service_notice field.
+! 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" |
+;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>.
+|}
-'''Example response:'''
+====Optional Arguments====
+{| class="spec-table arguments-table"
+! Field Name
+! class="spec-description"|Description
+! class="spec-requirements"| Notes & Requirements
+|-
+| class="field" |
+;lat
+| Latitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
+| <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.
+|-
+| class="field" |
+;long
+| Longitude using the [http://en.wikipedia.org/wiki/World_Geodetic_System (WGS84)] projection.
+| <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.
+|-
+| class="field" |
+;address_string
+| Human entered address or description of location.
+| 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.
+|-
+| class="field" |
+;address_id
+| The internal address ID used by a jurisdiction's master address repository or other addressing system.
+| 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.
+|-
+| class="field" |
+;media
+| An array of file uploads
+| A client may POST multiple files as multipart/form-data.  This is the equivalent of having multiple <input type="file" name="media[]" /> inputs.  Subsequent calls for GET Service Requests should return the URL for this file via the media_urls field. This means that a client can not simultaneously post a URL for media_url and post files via media. If this is done, the files uploaded via the media field will take precedence and be returned as URLs in the media_url field.
+|}
+====Response====
+{| class="spec-table"
+! Field Name
+! class="spec-description"|Description
+! class="spec-requirements"| Notes & Requirements
+|-
+!colspan="3" class="response-container"|service_requests ⇊
+|-
+!colspan="3" class="response-container"|request ↴
+|-
+| class="field" |
+; service_request_id
+| The unique ID of the service request created.
+| <span style="color: red">This should not be returned if token is returned</span>
+|-
+| class="field" |
+;  token
+| If returned, use this to call [[#GET_request_id_from_a_token|GET 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====
+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====
 <pre class="brush:xml">
+POST /dev/v2/requests.xml
+Host: api.city.gov
+Content-Type: application/x-www-form-urlencoded; charset=utf-8
-<service_requests>
+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
+</pre>
+'''Example response:'''
+<tabs>
+<tab title="XML">
+<pre class="brush:xml">
+<?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>
-<service_requests>
+</pre>
+</tab>
+<tab title="JSON">
+<pre class="brush:js">
+[
+  {
+    "service_request_id":293944,
+    "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",
+    "account_id":null
+  }
+]
 </pre>
-===GET token with request_id===
+</tab>
-*'''Purpose:''' get the request_id from a temporary token
+</tabs>
-*'''URL:''' https://open311.sfgov.org/dev/v2/tokens/123456.[format]
-*'''Sample URL:'''  https://open311.sfgov.org/dev/v2/tokens/123456.xml?jurisdiction_id=sfgov.org&api_key=xxxx
-*'''Formats: '''xml
-*'''HTTP Method: '''GET
-*'''Requires API Key: '''No
-*'''Required Arguments: '''
+===GET request_id from a token===
-** jurisdiction_id
+{| class="spec-table" class="method-table"
-** token
+!scope="row" | 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>
+|-
+!scope="row" | 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" | 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
+|}
-*'''Response:'''
-** service_request_id
-** token
-'''Example response:'''
+====Required Arguments====
+{| 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>
+|-
+| class="field" |
+;<span class="field-url">token</span>
+|
+| This is obtained from the [[#POST_Service_Requests|POST Service Requests]] method
+|}
-<pre class="brush:xml">
-<service_requests>
+====Response====
+{| class="spec-table"
+! Field Name
+! class="spec-description"|Description
+! class="spec-requirements"| Notes & Requirements
+|-
+!colspan="3" class="response-container"|service_requests ⇊
+|-
+!colspan="3" class="response-container"|request ↴
+|-
+| class="field" |
+; 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====
+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====
+<tabs>
+<tab title="XML">
+<pre class="brush:xml">
+<?xml version="1.0" encoding="utf-8"?>
+<service_requests>
 	<request>
 		<service_request_id>638344</service_request_id>
 		<token>12345</token>
 	</request>
 </service_requests>
 </pre>
+</tab>
+<tab title="JSON">
+<pre class="brush:js">
+[
+  {
+    "service_request_id":638344,
+    "token":12345
+  }
+]
+</pre>
+</tab>
+</tabs>
 ===GET Service Requests===
-*'''Purpose:''' query the current status of a request
+{| class="spec-table" class="method-table"
-*'''URL:''' https://open311.sfgov.org/dev/v2/requests.[format]
+!scope="row" | Purpose
-*'''Sample URL:'''  https://open311.sfgov.org/dev/v2/requests.xml?service_request_id=293450
+| Query the current status of multiple requests
-*'''Formats: '''xml
+|-
-*'''HTTP Method: '''GET
+!scope="row" | URL
-*'''Requires API Key: '''No
+| https://[API endpoint]/requests.[format]
-*'''Required Arguments: '''
+|-
-** none
+!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
+|}
-*'''Optional Arguments: '''
-** service_request_id
-** service_code (can be declared multiple times)
-** start_date & end_date (should not span more than 90 days) (w3 format)
-** status (open, closed, rejected, etc)
-** lat,long (requires radius, if not available, returns error)
+====Required Arguments====
-** radius (if not available, returns error)
+{| 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:'''
+====Optional Arguments====
-** service_request_id
+{| class="spec-table arguments-table"
-** status (open, closed, rejected (DC internally has open overdue and closed overdue statuses))
+! Field Name
-** status_notes
+! class="spec-description"|Description
-** service_name
+! class="spec-requirements"| Notes & Requirements
-** service_code
+|-
-** description (not all cities return descriptions)
+| class="field" |
-** agency_responsible
+;service_request_id
-** service_notice
+| To call multiple Service Requests at once, multiple service_request_id can be declared; comma delimited.
-** service_notice_datetime
+| This overrides all other arguments.
-** datetime_requested (w3 format)
+|-
-** updated_datetime (last time SR was modified, for closed SRs it will be closure date)
+| class="field" |
-** expected_datetime (optional, returns date SR should be closed based on SLA for this service)
+;service_code
-** address
+| Specify the service type by calling the unique ID of the service_code.
-** address_id
+| This defaults to all service codes when not declared; can be declared multiple times, comma delimited
-** zipcode
+|-
-** geo:lat
+| class="field" |
-** geo:long
+;start_date
-** georss:point
+| Earliest requested_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 requested_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" |
+;updated_after
+| Earliest updated_datetime to include in search. Allows one to search for requests which have an updated_datetime between the updated_after time and updated_before time (or now). This is useful for downloading a changeset that includes changes to older requests or to just query very recent changes.
+| Must use w3 format, eg 2010-01-01T00:00:00Z.
+|-
+| class="field" |
+;updated_before
+| Latest updated_datetime to include in search. Allows one to search for requests which have an updated_datetime between the updated_after time and the updated_before time. This is useful for downloading a changeset that includes changes to older requests or to just query very recent changes.
+| When not specified (updated_after is used without updated_before) then updated_before is assumed to be now. Must use w3 format, eg 2010-01-01T00:00:00Z. '''TODO: what happens when used without updated_after? Set a default range or range limit like start_date & end_date?'''
+|-
+| 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>
+|}
-'''Example response:'''
+====Response====
+{| class="spec-table"
+! Field Name
+! class="spec-description"|Description
+! class="spec-requirements"| Notes & Requirements
+|-
+!colspan="3" class="response-container"|service_requests ⇊
+|-
+!colspan="3" class="response-container"|request ↴
+|-
+| class="field" |
+; service_request_id
+| The unique ID of the service request created.
+|
+|-
+| class="field" |
+; status
+| The current status of the service request.
+* <span class="strict-value">open</span>: it has been reported.
+* <span class="strict-value">closed</span>: it has been resolved.
+| Options: <span class="strict-value">open</span>, <span class="strict-value">closed</span>
+|-
+| class="field" |
+; 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
+|-
+| class="field" |
+; service_name
+| The human readable name of the service request type
+|
+|-
+| class="field" |
+; service_code
+| The unique identifier for the service request type
+|
+|-
+| class="field" |
+; 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.
+|-
+| class="field" |
+; agency_responsible
+| The agency responsible for fulfilling or otherwise addressing the service request.
+| May not be returned
+|-
+| 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" |
+; requested_datetime
+| The date and time when the service request was made.
+| Returned in w3 format, eg 2010-01-01T00:00:00Z
+|-
+| 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.
+|}
-<pre class="brush:xml">
-<service_requests>
+====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====
+<tabs>
+<tab title="XML">
+<pre class="brush:xml">
+<?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://city.gov.s3.amazonaws.com/requests/media/638344.jpg </media_url>
+	</request>
+	<request>
+		<service_request_id>638349</service_request_id>
 		<status>open</status>
-		<status_notes/>
+		<status_notes></status_notes>
 		<service_name>Sidewalk and Curb Issues</service_name>
 		<service_code>006</service_code>
 		<description></description>
-		<datetime_requested>2010-04-14T06:37:38-08:00</datetime_requested>
+		<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>
-		<geo:lat xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#">37.762221815</geo:lat>
+		<lat>37.762221815</lat>
-		<geo:long xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#">-122.4651145</geo:long>
+		<long>-122.4651145</long>
-		<georss:point xmlns:georss="http://www.georss.org/georss">37.762221815 -122.4651145</georss:point>
+		<media_url>http://city.gov.s3.amazonaws.com/requests/media/638349.jpg </media_url>
 	</request>
 </service_requests>
+</pre>
+</tab>
+<tab title="JSON">
+<pre class="brush:js">
+[
+  {
+    "service_request_id":638344,
+    "status":"closed",
+    "status_notes":"Duplicate request.",
+    "service_name":"Sidewalk and Curb Issues",
+    "service_code":006,
+    "description":null,
+    "agency_responsible":null,
+    "service_notice":null,
+    "requested_datetime":"2010-04-14T06:37:38-08:00",
+    "updated_datetime":"2010-04-14T06:37:38-08:00",
+    "expected_datetime":"2010-04-15T06:37:38-08:00",
+    "address":"8TH AVE and JUDAH ST",
+    "address_id":545483,
+    "zipcode":94122,
+    "lat":37.762221815,
+    "long":-122.4651145,
+    "media_url":"http://city.gov.s3.amazonaws.com/requests/media/638344.jpg "
+  },
+  {
+    "service_request_id":638349,
+    "status":"open",
+    "status_notes":null,
+    "service_name":"Sidewalk and Curb Issues",
+    "service_code":006,
+    "description":null,
+    "agency_responsible":null,
+    "service_notice":null,
+    "requested_datetime":"2010-04-19T06:37:38-08:00",
+    "updated_datetime":"2010-04-19T06:37:38-08:00",
+    "expected_datetime":"2010-04-19T06:37:38-08:00",
+    "address":"8TH AVE and JUDAH ST",
+    "address_id":545483,
+    "zipcode":94122,
+    "lat":37.762221815,
+    "long":-122.4651145,
+    "media_url":"http://city.gov.s3.amazonaws.com/requests/media/638349.jpg"
+  }
+]
+</pre>
+</tab>
+</tabs>
+===GET Service Request===
+{| class="spec-table" class="method-table"
+!scope="row" | Purpose
+| Query the current status of an individual request
+|-
+!scope="row" | URL
+| 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====
+{| 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>
+|-
+| 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====
+None
+====Response====
+{| class="spec-table"
+! Field Name
+! class="spec-description"|Description
+! class="spec-requirements"| Notes & Requirements
+|-
+!colspan="3" class="response-container"|service_requests ⇊
+|-
+!colspan="3" class="response-container"|request ↴
+|-
+| class="field" |
+; service_request_id
+| The unique ID of the service request created.
+|
+|-
+| class="field" |
+; status
+| The current status of the service request.
+* <span class="strict-value">open</span>: it has been reported.
+* <span class="strict-value">closed</span>: it has been resolved.
+| Options: <span class="strict-value">open</span>, <span class="strict-value">closed</span>
+|-
+| class="field" |
+; 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
+|-
+| class="field" |
+; service_name
+| The human readable name of the service request type
+|
+|-
+| class="field" |
+; service_code
+| The unique identifier for the service request type
+|
+|-
+| class="field" |
+; 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.
+|-
+| class="field" |
+; agency_responsible
+| The agency responsible for fulfilling or otherwise addressing the service request.
+| May not be returned
+|-
+| 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" |
+; requested_datetime
+| The date and time when the service request was made.
+| Returned in w3 format, eg 2010-01-01T00:00:00Z
+|-
+| 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====
+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====
+<tabs>
+<tab title="XML">
+<pre class="brush:xml">
+<?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://city.gov.s3.amazonaws.com/requests/media/638344.jpg </media_url>
+	</request>
+</service_requests>
 </pre>
+</tab>
+<tab title="JSON">
+<pre class="brush:js">
+[
+  {
+    "service_request_id":638344,
+    "status":"closed",
+    "status_notes":"Duplicate request.",
+    "service_name":"Sidewalk and Curb Issues",
+    "service_code":006,
+    "description":null,
+    "agency_responsible":null,
+    "service_notice":null,
+    "requested_datetime":"2010-04-14T06:37:38-08:00",
+    "updated_datetime":"2010-04-14T06:37:38-08:00",
+    "expected_datetime":"2010-04-15T06:37:38-08:00",
+    "address":"8TH AVE and JUDAH ST",
+    "address_id":545483,
+    "zipcode":94122,
+    "lat":37.762221815,
+    "long":-122.4651145,
+    "media_url":"http://city.gov.s3.amazonaws.com/requests/media/638344.jpg"
+  }
+]
+</pre>
+</tab>
+</tabs>
 ===Errors===
-'''Response:'''
+====Response====
+{| class="spec-table" class="spec-table"
+! Field Name
+! class="spec-description"|Description
+! class="spec-requirements"| Notes & Requirements
+|-
+!colspan="3" class="response-container"|errors ⇊
+|-
+!colspan="3" class="response-container"|error ↴
+|-
+| class="field" |
+; 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.
+|
+|}
-* 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
-* '''General'''
+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).
-**  400   Missing API key
-**  401  Invalid API Key
-** 404  The URL request is invalid  or open311 service is not running or reachable. Client should notify us after checking URL
-*  '''/services''':
-**  408     General service error  ( -- Missing service list file , anything that happens during service_list processing. It should be follow by an error description. The client will need to notify us)
-*  '''/requests'''
-** 412   Missing service Code
-** 417   Invalid Service Code
-** 408   General Service Error ( anything captured during create_request processing ,  Lagan WS is down , ....An error description will follow. Client will need to notify us)
-*   '''/requests/12345.[format] '''
-**  409  Id not valid or you are attempting to search for a service request you did not create
-**  408  General Service error ( anything captured during status_update processing. It will always have an error description ..Client will have to notify us)
 '''Example:'''
+<tabs>
+<tab title="XML">
 <pre class="brush:xml">
-HTTP/1.1 401 Unauthorized
+HTTP/1.1 403 Forbidden
+<?xml version="1.0" encoding="utf-8"?>
+<errors>
+	<error>
+		<code>403</code>
+		<description>Invalid api_key received -- can't proceed with create_request.</description>
+	</error>
+</errors>
+</pre>
+</tab>
+<tab title="JSON">
+<pre class="brush:js">
+HTTP/1.1 403 Forbidden
-<error>Invalid api_key received -- can't proceed with create_request.</error>
+[
+  {
+    "code":403,
+    "description":"Invalid api_key received -- can't proceed with create_request."
+  }
+]
 </pre>
+</tab>
+</tabs>

Open311

Wiki

Personal tools

Views

Difference between revisions of "GeoReport v2.1 Draft"

Collaboration for an Open311 Standard

Latest revision as of 15:21, 25 September 2012

Contents

Status

Specification

Service Discovery

Internationalization and Encoding

Date/time format

Encoding

Format Support

XML Support

JSON Support

Definitions

jurisdiction_id

Optional Arguments

API methods

GET Service List

Required Arguments

Response

Possible Errors

Example response

GET Service Definition

Required Arguments

Response

Possible Errors

Example response

POST Service Request

Required Arguments

Optional Arguments

Response

Possible Errors

Example Request

GET request_id from a token

Required Arguments

Response

Possible Errors

Example response

GET Service Requests

Required Arguments

Optional Arguments

Response

Response Volume

Possible Errors

Example response

GET Service Request

Required Arguments

Optional Arguments

Response

Possible Errors

Example response

Errors

Response

Search

Tools

Navigation

Meta

Open311