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.
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:
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.
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:
https://data.cityofchicago.org/resource/f7f2-ggz5.json
Filtering data via a SODA API is fairly straightforward. There are two primary mechanisms you can use to filter data: Simple Filters and SoQL Queries
Filtering data is very straightforward. SODA APIs are self-describing — the schema and contents of the dataset itself determines how you can query it. Any field within the data can be used as a filter, simply by appending it to the API endpoint as a GET parameter. For example, to query for only fuel locations that provide Liquefied Petroleum Gas, simply append ?fuel_type_code=LPG to the URL:
https://data.cityofchicago.org/resource/f7f2-ggz5.json?fuel_type_code=LPG
Additional filters can be added, and the filters will be ANDed together.
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:
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:
https://data.cityofchicago.org/resource/f7f2-ggz5.json?$limit=100&$offset=100
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.