Application Tokens

The Socrata Open Data API uses application tokens for two purposes:

Using an application token allows us to throttle by application, rather than via IP address, which gives you a higher throttling limit
Authentication using OAuth

Note: The Socrata Open Data API has two concepts around API access: authentication and application tokens. You only need to authenticate if you wish to add, delete, or modify data that is attached to your account, or if you wish to read data you own that you have marked as private. Read-only requests only require the application token. See the SODA Producer API documentation for more details on changing data.

Throttling limits

Without an application token, we can only track usage and perform throttling based on a few simple criteria, mainly source IP address. As such, requests that aren’t using an application token come from a shared pool via IP address. IP addresses that make too many requests during a given period may be subject to throttling.

When requests are made using an application token, we can actually attribute each request to a particular application and developer, granting each their own pool of API requests. Currently we do not throttle API requests that are using an application token, unless those requests are determined to be abusive or malicious.

We reserve the right to change these throttling limits with notice, and we will post an update to announce any such change.

If you are throttled for any reason, you will receive a status code 429 response.

Don’t be a jerk!

Dont do that!

Yes, I know it says you get unlimited requests. But keep in mind that you’re using a shared platform, and you should still be deliberate in how you design your application to use our API. Applications that are determined to be abusive or malicious, or that otherwise monopolize the use of our API may be throttled.

If we detect that your application is nearing the point where we may have to throttle it, we will likely pro-actively reach out to you to discuss how you can optimize your usage. If you have any questions, feel free to contact us and we’d be glad to help!

Obtaining an Application Token

You can obtain an application token by registering for one in your Socrata profile.

Using your Application Token

While it is possible to perform simple unauthenticated queries against the Socrata Open Data API without making use of an application token, you’ll receive much higher throttling limits if you include an application token in your requests. If you elect not to use an application token, you’ll be subjected to a much lower throttling limit for all requests originating from your IP address.

There are two ways to include the application token in the request:

Use the X-App-Token HTTP header.
Use the $$app_token parameter in your request (app_token if you’re using old SODA 1.0 APIs).

Using the header is the preferred method.

Note: Application tokens are not necessarily used for authentication, but you should still preserve the security of your application token by always using HTTPS requests. If your application token is duplicated by another developer, their requests will count against your quota.

The following is an example of using the X-App-Token HTTP header to pass an application token:

GET /resource/kzjm-xkqj.json HTTP/1.1
Host: data.seattle.gov
Accept: application/json
X-App-Token: [REDACTED]

The same application token could also be passed as a URL parameter:

https://data.seattle.gov/resource/kzjm-xkqj.json?$$app_token=APP_TOKEN

Using the Application Token as part of the OAuth 2.0 authentication process

Application tokens can also be used for authentication using OAuth 2.0. For more information, see the authentication section.