Open311

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.

• Rate Limiting
• API Keys
• Extension Fields
• Service Requests Behaviors

Rate Limiting

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-After header to see if the server has given instructions on how long to wait until retrying your request.

API Keys

The Open311 spec indicates that an api_key parameter 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 Authorization header. Clients should present the token in the following form:

Authorization: Bearer API_KEY

where the string API_KEY is the actual API Key used by your application.

You may also provide the api_key parameter in the querystring or form parameters instead of the Authorization header, depending on your usage requirements and security considerations.

Extension Fields

If a client makes a request to the Get Service Definition, Get Service Requests or Get Service Request API calls with the parameter extensions set to 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:
  • x and 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 media_url, title and created_at.
• 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 q GET parameter to perform a text search across the available Service Requests that will be returned.
• updated_after and 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 100 is allowed.
• page: You may specify a given "page" to allow you to iterate over larger result sets.

Additionally, the date based parameters for searching (start_date, end_date, updated_after and 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_id value from the Get service_request_id from a token API operation.

When performing Get service_request_id from a token API operation it is advisable to always include your api_key, whether via querystring or Authorization header. Not including your api_key may cause you to receive 404 errors in many situations.