The “endpoint” of a SODA API is simply a unique URL that represents an object or collection of objects. Every Socrata dataset, and even every individual data record, has its own endpoint. The endpoint is what you’ll point your HTTP client at to interact with data resources.
All resources are accessed through a common base path of
/resource/ along with their dataset identifier. This paradigm holds true for every dataset in every SODA API. All datasets have a unique identifier - eight alphanumeric characters split into two four-character phrases by a dash. For example,
ydr8-5enu is the identifier for the Building Permits. This identifier can then be appended to the
/resource/ endpoint to construct the API endpoint.
You can also find API endpoints, and links to detailed developer documentation for each dataset in a number of different places, depending on where you are:
If you’re viewing a dataset directly, there will be an “API Documentation” button under “Export” and then “SODA API”. See this
If you’re viewing a dataset in Data Lens, there will be an API button you can click to get the API endpoint and a link to API documentation. See this
SODA and SoQL are very flexible, and allow us to add functionality over time without needing to completely deprecate and replace our APIs. We can do so in several different ways:
This allows us to introduce additional capabilities while still allowing you to issue the same kinds of queries in a backwards-compatible manner. We can extend SODA APIs without needing all developers to migrate their code to a new version.
However, some functionalities are not available on all of our API endpoints, which is why we differentiate between versions of a dataset’s API. Functions made available on a newer version might not be available on an API endpoint of an older version. In the sidebar of our automatic API documentation, we list the version that that endpoint complies with, as well as other useful information. See this
Throughout the documentation on this developer portal you’ll notice version toggles and info boxes that will help you understand the difference between SODA endpoint versions.
The first SODA 2.1 APIs (previously referred to as our “high-performance Socrata Open Data APIs”) were released in April of 2015 and in November of 2015 they received the “2.1” version designation for clarity. SODA 2.1 introduces a number of new datatypes as well as numerous new SoQL functions:
Textcomparisons becoming case-sensitive
New functionality will be added to this version over time.
For more information:
SODA 2.0 was originally released in 2011. Although 2.1 is backwards-compatible with 2.0, there are a number of differences between the two APIs:
Textcomparisons are case-insensitive
For more information:
In order to make sure you always have the latest version of the API available, we automatically migrate updates to a copy of the dataset of the latest endpoint version. In some cases, that process may fall behind, so in the API documentation for each dataset we display the “Sync Status” in the sidebar so you can check on it. See this
The simplest way to tell the difference between a 2.0 API and a 2.1 API is via the
X-SODA2-Legacy-Types header, which will be
true if you’re accessing a legacy 2.0 API.
From time to time, we’ll introduce new SoQL functions and datatypes to the latest version of the SODA API. Those changes will be non-breaking, and old queries and applications will continue to function unchanged. The SODA API is designed to make it easy to introduce new functionality over time without making breaking changes.
When we introduce breaking changes, such as the deprecation of a function or datatype, we’ll increment the SODA version and notify developers. Make sure you sign up for our developer newsletter so you can stay up to date!