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.
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://data.medicare.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", [ ] ] ] }
Root URL: http://data.medicare.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.
Root URL: http://data.medicare.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.
Root URL: http://data.medicare.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.
Root URL: http://data.medicare.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.
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.
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.