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