The STAC API family of specifications define a JSON-based web API to browse and query SpatioTemporal Asset Catalog (STAC) objects. While the core STAC specification provides a structure and language to describe assets, users usually want to access a subset of the entire catalog, such as for a certain date range, in a particular area of interest, or matching metadata properties. STAC API extensions specify those query parameters, and compliant servers return STAC Item objects that match the user's query. Additional functionality can be added through the OGC API family of standards, particularly OGC API - Features (OAFeat, for our shorthand). Notes on implementation recommendations may be found here.
The Core of STAC API returns a valid STAC Catalog and a description
of STAC API specifications to which it conforms. The links section of the Catalog is the jumping-off
point for the more powerful capabilities - it contains a list of URLs with link
'relationships' (rel) and descriptions to indicate their functionality. Note that the STAC Core specification provides
most of the content of API responses - the STAC API is primarily concerned with the return of STAC
Item and Collection objects via a
web API. See the rendered OpenAPI document for more details.
There are then two major sets of functionality that build on the core, Item Search and Collection and Features , which are designed to be complementary, letting implementations choose which parts they want to utilize.
The Item Search functionality is one of the most common, provided by the search rel
located at a /search endpoint. It re-uses all of the OAFeat query
parameters specified in their 'core', and adds a
few more. It does not require a full implementation of OAFeat, but it is instead a simplified construct that can run a
search across any group of STAC Item objects. See the rendered OpenAPI
document for more details.
The other major functionality for a STAC API is to serve STAC Collection and Item objects through
the OGC API - Features endpoints. This enables any OAFeat client
to access STAC Item objects in the same way they do any other data. Every STAC Collection becomes available at the
/collections endpoint (making this a superset of the Collections functionality), with each
/collections/{collectionId}/items endpoint allowing search of the items
in that single collection. For STAC, this means implementing OGC API - Features
Core, as well as
the OAFeat GeoJSON,
since STAC objects are by definition also GeoJSON objects.
Full compliance involves splitting STAC Item objects into
individual /collections/{collectionId}/items endpoints that expose querying single collections, as OAFeat does
not currently support cross-collection search. It also adds a few other requirements, which are highlighted in the
features description, in order to help STAC implementors understand OAFeat without having to
read the full specification from scratch. See the rendered OpenAPI document
for more details.
Both STAC API and OAFeat allow 'extensions' that can be added for additional functionality. The STAC community has
created a number of extensions to OAFeat
in order to meet the requirements of its implementors. Additional details about extensions can be found in the extensions document.
These are specified in OpenAPI, which works cleanly when the new functionality is a new API location (a complete
resource, or adding POST to an existing one). Many of the additions, however, are done at the parameter or response
level, like adding a sortby field to return ordered results.
Each extension is made specifically against a part of the STAC API, so that it can be specified as a conformance
class (e.g., that Item Search is being extended to support sortby but not Features).
We are working to fully align STAC's OAFeat extensions to be the same as the OGC API building blocks being worked on so that every STAC extension is specified at the OGC API level. The end goal is for STAC API to just present a curated set of extension options.
This version of STAC API depends on OGC API - Features - Part 1: Core Version 1.0. Future versions will likely depend on OGC API Common and additional parts of Features as components evolve and mature.
This version of STAC API (1.x.x) is intended to work with any STAC core specification version 1.x.x (including betas), but is not
designed to work with STAC 2.0 and above (since we use SemVer it may introduce backwards incompatible changes).
The STAC API spec is released with the latest stable STAC core specification version included in the /stac-spec
directory as a submodule. To determine which version it is, just check the
/stac-spec/CHANGELOG.md for the topmost version & release date.
STAC APIs follow the modern web API practices of using HTTP Request Methods ("verbs") and
the Content-Type header to drive behavior on resources ("nouns") in the endpoints listed below.
The following table describes the service resources available in a STAC API implementation that supports all three of the foundation specifications. Note that the 'Endpoint' column is more of an example in some cases. OGC API makes some endpoint locations required, those will be bolded below.
| Endpoint | Specified in | Link Relationship | Returns | Description |
|---|---|---|---|---|
/ |
Core | root | Catalog | Extends / from OAFeat to return a full STAC catalog. |
/search |
Item Search | search | ItemCollection | Retrieves a group of Item objects matching the provided search predicates, probably containing search metadata from the search extension |
/collections |
Features, Collections | data | JSON | Object with a list of Collection objects contained in the catalog and links |
/conformance |
Features | conformance | JSON | Info about standards to which the API conforms |
/api |
Features | service-desc | any | The description of the endpoints in this service |
/collections/{collectionId} |
Features, Collections | collection | Collection | Returns single Collection JSON |
/collections/{collectionId}/items |
Features | items | ItemCollection | GeoJSON FeatureCollection-conformant entity of Item objects in collection |
/collections/{collectionId}/items/{featureId} |
Features | item | Returns single Item (GeoJSON Feature). This relation is usually not used in OAFeat implementations. |
STAC API is evolving to utilize OAFeat's
Conformance
JSON structure. For
STAC API, we declare new STAC conformance classes, with the core ones detailed in the table below. STAC
Features requires the core OAFeat conformance classes and declares that those endpoints return
STAC Collection and Feature objects.
The core STAC conformance classes communicate the conformance JSON only in the root (/) document, while OGC API
requires they also live at the /conformance endpoint. STAC's conformance structure is detailed in the
core. Note all
conformance URIs serve up a rendered HTML version of the corresponding OpenAPI document at the given location.
| Name | Specified in | Conformance URI | Description |
|---|---|---|---|
| STAC API - Core | Core | https://api.stacspec.org/v1.0.0/core | Specifies the STAC Landing page /, communicating conformance and available endpoints. |
| STAC API - Item Search | Item Search | https://api.stacspec.org/v1.0.0/item-search | Enables search of all STAC Item objects on the server, with the STAC [/search](#stac-api-endpoints) endpoint. |
| STAC API - Features | Collections and Features | https://api.stacspec.org/v1.0.0/ogcapi-features | Specifies the use of OGC API - Features to serve STAC Item and Collection objects |
| STAC API - Collections | Collections and Features | https://api.stacspec.org/v1.0.0/collections | Specifies the use of a subset of STAC API - Features to serve Collection objects |
Additional conformance classes can be specified by STAC API Extensions.
When all three conformance classes (Core, Features, Item Search) are implemented, the relationships among
various resources are shown in the following diagram. In each node, there is also a self and root link
that are not depicted to keep the diagram more concise.
The Landing Page will at least have the following conformsTo and links:
{
"stac_version": "1.0.0",
"id": "example-stac",
"title": "A simple STAC API Example",
"description": "This Catalog aims to demonstrate the a simple landing page",
"type": "Catalog",
"conformsTo" : [
"https://api.stacspec.org/v1.0.0/core",
"https://api.stacspec.org/v1.0.0/collections",
"https://api.stacspec.org/v1.0.0/ogcapi-features",
"https://api.stacspec.org/v1.0.0/item-search",
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core",
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
"http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
],
"links": [
{
"rel": "self",
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "root",
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "conformance",
"type": "application/json",
"href": "https://stac-api.example.com/conformance"
},
{
"rel": "service-desc",
"type": "application/vnd.oai.openapi+json;version=3.0",
"href": "https://stac-api.example.com/api"
},
{
"rel": "service-doc",
"type": "text/html",
"href": "https://stac-api.example.com/api.html"
},
{
"rel": "data",
"type": "application/json",
"href": "https://stac-api.example.com/collections"
},
{
"rel": "child",
"type": "application/json",
"href": "https://stac-api.example.com/collections/sentinel-2",
},
{
"rel": "child",
"type": "application/json",
"href": "https://stac-api.example.com/collections/landsat-8",
},
{
"rel": "search",
"type": "application/geo+json",
"href": "https://stac-api.example.com/search"
}
]
}