Getting Started with SODA 2.0

The Socrata Open Data API version 1.0 is in the process of being deprecated and replaced by the new SODA 2.0 API. For more information view SODA 2.0 release announcement. For information on the deprecated SODA 1.0 APIs is available here.

In addition to our code samples on Github, we also provide simple runnable examples inline with the documentation. In order to make the examples as language-agnostic as possible, and to show how you can use the SODA API with the simplest tools possible, examples are provided in-line using the SODA Console. Wherever you see a link like http://soda.demo.socrata.com/resource/earthquakes.json, you can click it to dynamically run that request in the SODA Console “visor”. You can examine the URL that was constructed, see what results were returned, and experiment, all without ever leaving the page you’re currently on.

A few examples:

SODA 2.0 Datasets and Custom APIs

On the Socrata platform, every dataset is automatically provided with a simple API. That ensures that every developer has at least programmatic access to every dataset on our platform, regardless of the actions of the dataset owner.

Some data publishers may opt to use Socrata’s API Foundry product to create custom APIs for their datasets. When creating a custom API, data publishers can customize the schema, functionality, and endpoint of their API to their needs. Custom APIs also are provided automatically generated, customizable documentation pages and entry in that site’s API catalog, like the developer portal for soda.demo.socrata.com.

SODA 2.0 Endpoints

In SODA 2.0, the endpoint for every dataset and custom API is by default hosted under /resources. Datasets are addressable by that dataset’s unique identifier, which you can locate either in the “API” sidebar on the dataset or as the 4x4 code at the end of any dataset URL. Custom APIs have a custom address under /resources that you can discover in that data site’s /developer portal.

For example, the USGS Earthquake Reports set on soda.demo.socrata.com has a unique identifier of 4tka-6guv, so its API endpoint is https://soda.demo.socrata.com/resource/4tka-6guv.json. However, a custom API has also been created for it and, as stated in its API documentation, its custom endpoint is at https://soda.demo.socrata.com/resource/earthquakes.json.

API Schemas

The schema of the output of SODA 2.0 APIs is determined either by the structure of the dataset itself, or by the configuration that the data owner applied using the API Foundry. In either case, each column in the dataset is represented as a field within the output that is keyed by its field name. Field names can be distinct from the human-readable name for a column, but are designed to be best used with the API.

The actual format differs depending on the output type you have selected (see the Available Data Formats section below), but take, for example, the JSON output for the USGS Earthquakes API we’ve been working with:

[
    {
        "region": "British Columbia, Canada",
        "source": "uw",
        "location": {
            "longitude": -120.5032,
            "latitude": 49.4012
        },
        "magnitude": 2.3,
        "number_of_stations": 11,
        "datetime": "2012-09-13T23:06:29",
        "earthquake_id": "60451507",
        "depth": 0.00,
        "version": "2"
    },
]

Each column is represented by a unique field name. Conveniently, the schema details for the API are included in the HTTP response headers with every request as X-SODA2-Fields and X-SODA2-Types:

X-SODA2-Fields: ["region",":updated_at","source","location","magnitude ","number_of_stations",":id","datetime",":created_at","earthquake_id","d epth","version"]
X-SODA2-Types: ["text","meta_data","text","location","number","number" ,"meta_data","calendar_date","meta_data","text","number","text"]

Querying with SoQL

If you perform a GET request on an API endpoint using an HTTP client (such as a web browser, a simple utility like cURL, or a REST client like Postman), you will automatically get the first 1000, unfiltered records.

To perform simple equality queries, simply use the field name as a GET parameter with the your chosen filter as the value. For example, to query the USGS Earthquakes API for quakes with a region of Washington:

https://soda.demo.socrata.com/resource/earthquakes.json?region=Washington

In addition to this base functionality, SODA 2.0 adds a rich query language to let you build expressive queries. Here is set of progressively more complex queries that could be added to the endpoint for more interesting results:

For those looking for a little more in the way of geo-queries, we offer those as well. You can perform bounding-box queries using within_box:

Available Data Formats

The Socrata Open Data API supports a number of different formats, including JSON, XML, CSV, and RDF. To change the output format of a request, simply change the extension you use on the resource you are trying to receive.

Most of the API examples use the JSON format, as it is the most compact and efficient format we provide.

Authentication, Application Tokens, and Throttling

If you only wish to consume data from the Socrata Open Data API, you don’t need to worry about authentication. However, all requests are subject to throttling to protect one application, malicious or otherwise, from affecting the availability of the API for everyone else using it. If you’re going to be making a large number of requests, register your application for an application token. You’ll receive higher request quotas, and you’ll also receive free publicity for your app. What’s not to love?

If you wish to act on behalf of a Socrata user, however, you will need to use one of the SODA API’s two authentication methods. The API is built to authenticate primarily with OAuth 2. We support only the server-based flow with a callback URL for security reasons. Please see the API Authentication and Application Tokens section for further details on authenticating using OAuth 2.

If you’re only writing a quick application to authenticate as yourself, or you are unable for some other reason to use OAuth 2, the SODA API provides a fall-back authentication method using HTTP Basic authentication. Simply use the email address and password you registered with Socrata. When making authenticated requests, please remember to always use HTTPS connections, and to supply an application token.

blog comments powered by Disqus

powered by toto