Open311
San Francisco 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.
-
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 theRetry-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 HTTPAuthorization
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 theAuthorization
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 totrue
, 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 requestsnotice
: 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 attributevalue
: A human readable value for this attributename
: The API readable "key" that is used for this attributecode
: 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
andy
: The location of the Service Request as 2D coordinates in the projection ESRI:102643photos
: An array of dictionaries that represent all public media associated with this Service Request. Each dictionary may contain the keysmedia_url
,title
andcreated_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 createddescription
: 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 aq
GET parameter to perform a text search across the available Service Requests that will be returned.updated_after
andupdated_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 of100
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
andupdated_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'sservice_request_id
value from the Getservice_request_id
from a token API operation.When performing Get
service_request_id
from a token API operation it is advisable to always include yourapi_key
, whether via querystring orAuthorization
header. Not including yourapi_key
may cause you to receive 404 errors in many situations.
Need Help?
Can’t find the answer you’re looking for? Reach out to our team.