Getting Started with the Socrata Open Data API

About the Examples

In addition to our code samples, we also provide simple 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 get("http://opendata.socrata.com/api/users/i7d8-sc4w.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:

• Get the author's user profile: get("http://opendata.socrata.com/api/users/i7d8-sc4w.json")
• Get metadata for a view: get("http://opendata.socrata.com/api/views/n5m4-mism.json")
• Get five rows from the same view: get("http://opendata.socrata.com/api/views/n5m4-mism/rows.json?max_rows=5")

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 fallback 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.

• For more information, see the API Authentication and Application Tokens section.

The RESTful Data Model

Wherever possible, the Socrata Open Data API strives to be as RESTful as possible. Resources are represented in a hierarchical manner, and the service uses the standard HTTP GET, POST, PUT, and DELETE methods to manipulate those resources. We also use JSON, XML, and RDF to represent resources. For example:

• Datasets and filtered views are represented using the top level /api/views resource. To retrieve a list of views in JSON format, use a GET request on the /api/views.json resource in order to get a list of the views that are available: get("http://opendata.socrata.com/api/views.json?limit=5")
• To get information about a particular view, add its resource ID to the /api/views resource. IDs in SODA are 8 alphanumeric characters, separated by a dash in the middle, in a "4-4" format: get("http://opendata.socrata.com/api/views/n5m4-mism.json")
• If you want to then retrieve rows on a particular view, you'd tack on the rows resource to its view resource: get("http://opendata.socrata.com/api/views/n5m4-mism/rows.json?max_rows=5")
• You can even directly reference an individual row on a dataset by identifying it by row ID: get("http://opendata.socrata.com/api/views/n5m4-mism/rows/418.json")

You can traverse the hierarchy for most resources in this manner to directly access their children.

• For more information on accessing datasets and view metadata, see Accessing View Metadata.
• For more information on accessing and filtering for rows, see Retrieving Row Data

Available Data Formats

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

• .json, for JSON formatting. Works on all resource types: get("http://opendata.socrata.com/api/views/n5m4-mism.json").
• .xml, for XML formatting. Works on all resource types: get("http://opendata.socrata.com/api/views/n5m4-mism.xml").
• .rdf, for RDF formatting. Works on most resource types: get("http://opendata.socrata.com/api/views/n5m4-mism.rdf").
• .xls and .xlsx, for Excel XLS output. Works only on row data: http://opendata.socrata.com/api/views/n5m4-mism/rows.xls
• .csv and .txt, for Comma Separated Value and text output types. Works only on row data: http://opendata.socrata.com/api/views/n5m4-mism/rows.csv
• .pdf, for a printable Adobe PDF version of a dataset. Works only on row data: http://opendata.socrata.com/api/views/n5m4-mism/rows.pdf

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