This is the documentation for the Socrata Open Data "Consumer" API. Socrata API are sets of REST resources you can use to manage Socrata entities and data. Resources are grouped by areas of related high-level functionality. The sections that follow document individual services in detail.

Code samples and other examples are also available at http://github.com/socrata. Feel free to fork our projects and submit pull requests if you make bug fixes or improvements. You can also participate in discussions in our Developer Forums.

About the Examples:

In addition to the code samples on Github, 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 using the *nix "cURL" command. "cURL" is an open-source command line utility that is usually installed by default on Linux and Mac OS X, and is available on Windows through packages like Cygwin. It allows you to make simple HTTP requests from your command line, and to interact with those results.

For example, here's how you'd perform a simple search on a dataset using the cURL command (I've truncated the output for clarity):

> curl "https://explore.data.gov/api/views/e4ie-ajsp/rows.json?search=541"
{
  "meta" : {
    "view" : {
      "id" : "e4ie-ajsp",
      "name" : "Simple",
      "averageRating" : 80,
      "createdAt" : 1267637009,
      ...
      "flags" : [ "default", "schemaPublic" ]
    }
  },
  "data" : [ [ 4, "050DB7E6-E963-49F3-BAB1-9CCFB8EB5C8D", 4, 1267637390, "4", 1267637390, "4", null, "516", "541", [ ] ]
, [ 249, "05EEC62E-7272-47F9-B161-8993F813609C", 249, 1267637391, "4", 1267637391, "4", null, "541", "933", [ ] ]
 ]
}

Authenticate Service

Root URL: http://explore.data.gov/api/authenticate

Compliance Level: This service is a Socrata extension to the SODA standard

The AuthenticationService offers an alternative cookie based authentication method. Using the AuthenticationService, you can request a cookie that can be included with subsequent requests.

Docs Service

Root URL: http://explore.data.gov/api/docs

Compliance Level: This service is a Socrata extension to the SODA standard

The DocsService allows for the retrieval of automatically-generated service documentation This service is most commonly accessed using a web browser, like you are doing right now. The service also supports a compact JSON format that describes services and resources, which can be retreived by appending .json to any /docs URL.

Users Service

Root URL: http://explore.data.gov/api/users

Compliance Level: This service is a Socrata extension to the SODA standard

The UsersService allows you to retrieve details of user profiles, as well as to manage your own user profile. User profiles include the user's username, given name, and user ID, as well as profile details such as their hometown and profile image. In addition, you can also retrive a user's contacts, groups, picklists, and views. For details on what is available, see the documentation on the User type.

Views Service

Root URL: http://explore.data.gov/api/views

Compliance Level: This service is required by the SODA standard

The ViewsService allows you to retrieve and manipulate metadata about datasets and views, as well as to query for datasets and views that match given search criteria. It also allows you to create, read, update, and delete rows of data from datasets and views.

Types

Input and output to Socrata services consists of different types of data elements. Types include primitive types such as strings and integers as well as complex types that are composed of other types.

This section describes Socrata API types in detail.

Errors

When an operation fails because of an error, Socrata services return an HTTP error code and include additional details in the response body. Error details include a message and an error code. Error codes are standardized across services.