The Open311 API provides a way to work with service requests between citizens, governments and non-governmental organizations.
Open311 is decentralized. There is no central registry to which a providing system is required to register. There is also no central authority that lists the responsible Open311 providers for a particular location or set of concerns.
Open311 is intended to be applicable every where for all languages. The spec has been initially written in English with English terms solely for the convenience of the authors. All attempts were made to provide for the API to work for all language locales.
Open311 uses only standard HTTP requests and responses.
The Open311 API is a RESTful service. All GET requests are idempotent, they have no side effect other then returning data in a response to the client.
It is expected that multiple versions of the Open311 API will exist and interoperate concurrently. The spec is designed to allow service providers of different versions to be able to communicate together.
Terminology
Provider or Service Provider
The system on which the API calls are made. This is the system that is mapped to by the URIs that a client makes HTTP calls to.
Client
The entity or system from which API calls are made. This could be a citizen's browser, a third party computer system or another service provider.
Issue
A specific, geographically stationary, concern that has a concrete definable fix. Some common names include: service request, work order or ticket.
Citizen
Any natural person.
Non-Governmental Organization
An entity that is not a government.
Government
The organization that manages a political unit of any size.
Locale
The collection of configuration that is necessary to contextualize specific content for a particular language format. For example language or numerical formatting that configures a system for a specific known language. Locales are usually originated in a specific geographic region. However the Open311 API expects them to only refer to the configuration necessary localize content for that locale. See http://en.wikipedia.org/wiki/Locale
Latitude / Longitude
All latitudes and longitude values MUST be WGS84 (World Geodetic System 1984) datum values expressed in decimal format. See http://en.wikipedia.org/wiki/WGS84
For Example: 37.40320,-121.977521
Area of Interest
An area of interest is a bounded geographical area inside which a service provider will accept issue reports. Areas of interest are independent of the locales that a provider supports. Providers MAY support any area(s) of interest independently of which ever locale(s) they wish to support.
Root URI
A root URI defines the start point for the API for a particular service provider. It is defined by the service provider and takes the form of: http://<host>[/path]
Messages MUST NOT contain multiple keys with the same name.
Throughout this document, all Open311 parameters are REQUIRED unless marked as OPTIONAL with square brackets eg [example]
Open311 expects RESTful semantics on all URIs exposed by providers. This means that all GET requests MUST be idempotent. Said another way, GET requests return data with out making any change to the data at the service provider. To change data at a service provider the client must use a PUT, POST, or DELETE request.
HTTP Encoding
When a message is sent to an HTTP server, it MUST be encoded using a form encoding specified in Section 17.13.4 of HTML401. Likewise, if the "Content-Type" header is included in the request's headers, its value MUST also be of such an encoding.
Locale
The Open311 API is intended for planet wide applicability. It is expected that there will be service providers that only support a single language locale. This locale MAY or MAY NOT be the primary locale for the areas of interest the service provider supports. It is also expected that there will be service providers that support several locales. Again these locales MAY or MAY NOT be the default primary locale for the areas of interest the service provider supports.
If a client submits a request a service provider with no locale defined, then the service provider's response MUST be consistent with the default locale the service provider returns from the "/info" resource.
If a client submits a request to a service provider with a locale that is included in the provider's list of supported locales then the service providers response MUST be consistent with the language locale specified in the request.
If a client submits a request to a service provider with a locale that is not included in the provider's list of supported locales then the service provider's response MAY be consistent with any language locale that the service provider supports.
Locale values MUST conform to [RFC 4646] definitions. See http://tools.ietf.org/html/rfc4646
Resources
Any request or response parameters marked in square brackets like this: [example], MUST be considered optional. All other parameters MUST be considered required.
Resource URIs MAY be suffixed with the format the client prefers to receive its response. Clients SHOULD NOT request any formats other then:
-JSON
-HTML
-XML
Providers SHOULD respond to these requests with properly formatted responses. If no format is specified then the service provider SHOULD respond with an HTML formatted response.
The implementation of the HTML response is intended to be human read-able. The specific format of which is left to the discretion of the service provider. Clients SHOULD NOT expect the format of the HTML responses to be be consistent between service providers or through time for the same service provider.
/versions
Description
This base resource is intended to be used to provide clients with information on which versions of the Open311 API the provider supports.
GET
Accepts:
-no parameters-
Returns:
versions: List of supported API versions
Description
The info method is intended to return general system level information about the service provider. If no areas of interest are returned it is expected that the provider is interested in service requests in all areas. The provider doesn't return a list of areas of interested they SHOULD NOT error a service request create method for not existing inside an area of interest.
GET
Accepts:
[locale]
Returns:
name: Provider Name
contact_info: Provider Contact Info
MUST include one of the following: phone, email or postal address
default_locale: Default Locale
locales: List of Supported Locales
areas: List of areas of interest
Each list of lat/lngs MUST be defined clockwise so as to disambiguate in vs out
Each list is a string of space delimited comma seperated pairs of latitude,longitude
GET
Accepts:
[locale]
Returns: Success
issues: List of issues
Failure locale
Error Description
PUT
Accepts:
[locale]: Language locale desired in reponse
summary: Short title for the issue.
[description]: Longer write up of exactly what the issue pertains to.
tags: comma delimited list of tags to apply to the issue.
display_name: How the reporter wishes to be identified as the reporter
lat: The latitude of the issue
lng: The longitude of the issue
[callback]: URI that the client requests notification calls be sent to in the event of this issue being updated.
Returns: Success
Same as GET to http://<root>/v1/issue/<id>
Failure locale
Error Description
POST / DELETE
Not supported.
/v1/issue/<id>
This resource represents a specific issue inside of the service provider's system. The id is defined by the service provider at the time the issue is created. The id MUST stay consistent so that the same id always points to the same issue. The service provider MUST ensure that the id is unique inside of its own system and across versions of the API. It is not expected that the id is unique accross service providers.
GET
Accepts:
[locale]
summary
description
tags
callback URI
display name
lat/lng
Returns: Success
request id
Failure
Error Code
Error Description
/v1/tag
Many municipalities or other governmental organizations have extensive internal taxonomies for issue classification. The Open311 API intentionally eschews rigid taxonomies. Instead the API supports free form tagging.
To allow providers to help promote a coherent tag structure for submitted issues, providers MAY support this resource. If providers do not implement this then they MUST provide an empty list with an unsupported operation HTTP response code. If the client makes a call to this resource it gives the provider an opportunity to suggest a list of possible tag completion values that the provider would encourage the client to submit.
The client MAY use a value from this returned list. The provider MUST accept any tag that is submitted by the client.
GET
Accepts:
[locale]: The desired language locale for the response.
[tag]: Some or no portion of a tag
Returns: Success
Ordered list of suggested tags Failure
Locale
Error Description
PUT / POST / DELETE
Not supported.
/v1/callback/<source URI>/<resource>...
This is the resource that will be called by a client if that client was a provider that had a callback registered with it for the provider URI that it is now calling.
To register a call back the caller MUST provide a URI. This URI MUST refer to a Open311 compliant provider system. If the service provider accepts the registration of a callback URI on a service request, the provider MUST make calls to the URI when state on that service request changes.
Example:
System A calls System B with a PUT: (only the callback is listed for simplicity)
Request: http://systemb.net/api/issue?callback=http://systemA.net/open311/
Response: { "id" : "12345678" }
Some internal work flow changes the status of http://systemb.net/api/issue/12345678 from "Open" to "Closed". System A MUST call System B with the following POST:
Request: http://systemA.net/open311/callback/systemb.net/api/issue/12345678?status=Closed
/v1/search
The purpose of the search method is to return data associated with a service requests that match the query submitted. The specific algorithm for matching the query submitted to particular issues is solely at the discretion of the provider. It is SUGGESTED that the algorithm maintain consistency between searches that are performed soon after each other. However clients SHOULD NOT expect to always get the same result set back for the same query from the same provider.
Each provider MAY implement rate limiting or max result set sizing in order to better shape the load on their system.
GET
Accepts:
[locale]
query: The query string
Returns: Success
List of issues Failure
locale
Error Description
PUT / POST / DELETE
Not supported.
/v1/find
The purpose find resource is find issues that match the particular attributes that are submitted.
[tags]
[keywords]
other attributes of issue?
Returns: Success
List of issues
Failure
locale
Error Description
PUT / POST / DELETE
Not supported.
Acknowledgments
This work attempts to stand on the shoulders of giants. Taking a stab at a thank you list would inevitability leave out a worthy party. This spec is not intended to promote an original idea, on the contrary, it is intended to codify the thinking of many others. Thank you to all. We would be remiss if we did not mention that the language in this spec is heavily borrowed from the OpenID Authentication 2.0 Specification. Much appreciation is directed to their efforts.
Open Questions
Authentication
Q: How do we handle authentication?
Q: Is it required of optional?
Authorization
Q: How do we handle API keying?
Q: Is it required or optional?
Q: Should there be an automated request/response mechanism in the API?
Q: Are providers allowed to rate limit clients? If so are there guidelines?
Errors
Q: Should all messages return status 200?
Q: Should all error messages be human readable?
Q: Should all error messages be localized to the requested or default locale?
Client Based Request Identifiers
Q: Would supporting client based request identifiers that allow clients to replay requests without repetitive effects be worth while?
Q: How long is the provider expected to track these
Refusal of Service
Q: May providers refuse service at their discretion?
Q: Does the type of provider entity matter?
Q: How does a service provider reject PUT/POST/DELETE? Do rejects trigger callbacks?
Comments
Q: Is the initial description considered a comment on the issue?
Q: Can anyone add comments to issues?
Citizens
Orgs
Gov
Media