BOS:311 API Documentation
Open311 API Addendum
Our implementation of the Open311 API has been extended to add new fields and behaviors. Some of this behavior has been taken from City of Chicago extensions to the Open311 API, and some are unique to this implementation.
By default, all users of the Open311 API are limited to 10 requests per minute. If you would like to increase your usage, you may request an application key that would allow you to have increased usage. The application key must be used in both read and write requests in order for your updated usage limits to be applied.
In all cases, you should assume that if you receive an HTTP status response of
429, that your request has been rate limited. You should check the contents of the
Retry-Afterheader to see if the server has given instructions on how long to wait until retrying your request.
The Open311 spec indicates that an
api_keyparameter be provided only in a Create Service Request context. Our implementation allows for an API key to be presented in any API request by allowing it to be passed in the HTTP
Authorizationheader. Clients should present the token in the following form:
Authorization: Bearer API_KEY
where the string
API_KEYis the actual API Key used by your application.
You may also provide the
api_keyparameter in the querystring or form parameters instead of the
Authorizationheader, depending on your usage requirements and security considerations.
If a client makes a request to the Get Service Definition, Get Service Requests or Get Service Request API calls with the parameter
true, we will return additional information regarding the Service Definition or Service Request. This information is not guaranteed to be present in future API requests, and is not considered a formal addition to the Open311 specification. We may remove access to that data in the future to ensure the overall quality of the Open311 API.
For Service Definition responses, we will return an additional key in the response that is named
extended_attributes. This field will contain additional context regarding the service definition. Two fields that may be included in the response include:
active: A boolean value indicating whether or not the Service is currently accepting new requests
notice: A string value with further instructions or information regarding the Service and its usage
For Service Request responses, we may return the additional optional keys.
details: A dictionary of keys and values that represent Service specific attributes unique to this particular Service Request.
attributes: An array of dictionaries that represent the Service specific attributes unique to to this particular Service Request. Each dictionary may have the following keys:
label: A human readable label for this attribute
value: A human readable value for this attribute
name: The API readable "key" that is used for this attribute
code: The API readable "value" that is used for this attribute, typically present in cases where a user picks a value from a list to populate this entry
extended_attributes: Additional values unique to this Service Request, including:
y: The location of the Service Request as 2D coordinates in the projection ESRI:102686
photos: An array of dictionaries that represent all public media associated with this Service Request. Each dictionary may contain the keys
notes: An array of dictionaries representing all public notes associated with this request. These dictionaries may include the following keys:
datetime: When the note was created
description: A human readable string of the notice
Service Requests Behaviors
The Get Service Requests API call supports additional behaviors to allow further refining the set of Service Requests returned. These additional behaviors are:
q: You may specify a
qGET parameter to perform a text search across the available Service Requests that will be returned.
updated_before: These two ISO8601 date values may specify the range of Service Requests that should be returned should have been updated in the provided date range. Please note that many operations may update a Service Request, and not all of them may be visible through the Open311 API.
per_page: How many search results to return. A maximum of
page: You may specify a given "page" to allow you to iterate over larger result sets.
Additionally, the date based parameters for searching (
updated_before) all are limited to a duration of 90 days.
Each Service Request response returned by the server will always include a field named
token, which is the value that may be used to fetch that Service Request's
service_request_idvalue from the Get
service_request_idfrom a token API operation.
When performing Get
service_request_idfrom a token API operation it is advisable to always include your
api_key, whether via querystring or
Authorizationheader. Not including your
api_keymay cause you to receive 404 errors in many situations.
Can’t find the answer you’re looking for? Reach out to our team.