Getting started with the SODA Consumer API

So you want to win that hackathon or build the next hot open data app? Follow this guide to get yourself started. Make sure you check out the more detailed resources under the “API Docs” section when it’s time to get in deep.

Locating Open Data and APIs

Socrata hosts over one hundred different data catalogs for governments, non-profits, and NGOs around the world, so finding an open data catalog to work with is easy:

• Check to see if your local government or state already has an open data site. Check your city or state website or even just Google “open data” and your government’s name. You’ll probably find something pretty quickly.
• Peruse the Open Data Network, our global catalog of open datasets. The same catalog listing is also available programmatically via the Discovery API.

Once you’re on your local open data site, navigate to the data catalog (append /browse to the base URL of the site) and use the search box and browse filters to find datasets that interest you - every dataset is accessible via the SODA API.

Finding your API endpoint

Every Socrata open dataset has a built-in SODA API. But how you find the API endpoint can vary a bit.

If you’re viewing a DataLens, there will be a prominent “API” button in the upper left of the page. Click that, and you’ll get details on the API endpoint and a link to API documentation.

If you’re on a Socrata dataset, identifiable by the colorful buttons at the upper right, don’t fret. Every Socrata dataset has a built-in open data API, so you’ll be just fine. Click on Export and then API and you’ll find the API endpoint under API Access Endpoint. Copy that and save it for later.

For this example, we’ll use this listing of Alternative Fuel Locations in Chicago:

Building simple filters and queries

Filtering data via a SODA API is fairly straightforward: SoQL Queries

SoQL Queries

The “Socrata Query Language” (SoQL) is a simple, SQL-like query language specifically designed for making it easy to work with data on the web. The language is both powerful and easy to learn, and everything works via GET parameters. For example, to search for fuel stations in downtown Chicago:

Paging

For performance, SODA APIs are paged, and return a maximum of 50,000 records per page. So, to request subsequent pages, you’ll need to use the $limit and $offset parameters to request more data. The $limit parameter chooses how many records to return per page, and $offset tells the API on what record to start returning data.

So, to request page two, at 100 records per page, of our fuel locations API:

Throttling and Application Tokens

Hold on a second! Before you go storming off to make the next great open data app, you should understand how SODA handles throttling. You can make a certain number of requests without an application token, but they come from a shared pool and you’re eventually going to get cut off.

If you want more requests, sign up for a Socrata account, then register for an application token and your application will be granted up to 1000 requests per rolling hour period. If you need even more than that, special exceptions are made by request. You can contact our support team here.