Getting Started with the Socrata Open Data Publisher API

About the Publisher API

The Socrata Open Data API's Publisher API is strictly a superset of the features provided in the Consumer API — in fact, they are one and the same. For details on how to access information, please refer to the Consumer API documentation. For those of you who wish to publish data, however, venture bravely onwards!

Authentication, Application Tokens, and Throttling

If you wish to publish data using the Socrata Open Data API, 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 simpler 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.

Getting Data in through the Socrata Open Data API

There are two primary interfaces for publishing your data through the API: for new data for which there is already a source data file, the Import API will allow you to upload, transform, and describe your data however you wish so that it looks the way you desire. For data that needs frequent updating, the SODA API includes a RESTful API for interacting with datasets that are already on the platform.

• For more information on the Imports API, see the importing 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.