A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns STAC Items (GeoJSON objects with required links, time stamp and links to assets) from search queries on a RESTful endpoint, and also offers an endpoint to return STAC Items as a compliant STAC Catalog for discovery.
The core of the spec is a single endpoint:
/stac/search
It takes a JSON object that can filter on date and time:
{
"bbox": [5.5, 46, 8, 47.4],
"time": "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
}This tells the server to return all the catalog items it has that are from the second half of March, 2018 and that intersect with this area:
Map © OpenStreetMap contributors
The return format is a GeoJSON FeatureCollection with features compliant with the
Item spec for STAC. It returns to a limit optionally requested by the client, and includes
pageable links to iterate through any results past that limit.
The other endpoint that is included as an option in STAC API is /stac/, which implements the STAC Catalog Spec.
Implementing this enables tools like
STAC Browser to use the dynamic catalog, to enable better
discovery through people browsing and search engines crawling.
The OpenAPI spec in this directory documents the endpoint, and refer to the STAC Catalog and STAC Collection for more information about the full content and link structure.
The STAC API should be simple to implement and extensible. To support that goal, the extensions are broken out into fragments. These fragments should allow an implementor to layer on additional functionality as needed.
We have structured our OpenAPI YAML files so that that can be joined together with import statements to prevent copying the
extensions into every possibly combination. In the api-spec folder you can expect to find complete OpenAPI definitions that are
useable as-is. For developers who want to author their own extension or combine extensions into a new OpenAPI defintion file, see below.
The definitions folder contains the YAML files that will import fragments and output a complete definition. These are not directly usable in OpenAPI as they have import directives that need to be resolved.
See yaml-files for the syntax to import YAML fragments.
The fragments folder contains valid yaml that is intended to be merged into an openapi document. It should be possible to import one or more fragments at the same time to create a new STAC+extensions definition.
To rebuild all definitions run the included Node.js scripts.
npm install
npm run generate-allThe definitive specification for STAC is the OpenAPI 3.0 YAML document. This is available in several forms. The most straightforward for an implementor new to STAC is the STAC-standalone.yaml. This gives a complete service with the main STAC endpoint. See the online documentation for the API rendered interactively.
The core STAC API includes two filters - Bounding Box and Time. All STAC Items require space and time, and thus any STAC client can expect to be able to filter on them. Most data will include additional data that users would like to query on, so there is a mechanism to also specify more filters. See the Filtering document for additional information on the core filters as well as how to extend them. It is anticipated that "extensions" for domains (e.g. earth observation imagery) will require additional fields to query their common fields.
At the Fort Collins Sprint the decision was made to align STAC with the WFS 3 specification, as they are quite similar in spirit and intention. It is anticipated that most STAC implementations will also implement WFS, and indeed most additional functionality that extends STAC will be done as WFS extensions.
This folder thus also provides an OpenAPI fragment, as well as an example service (YAML) for those interested in what a server that implements both STAC and WFS would look like. Those interested in learning more can read the deeper discussion of WFS integration.
The POST endpoint is required for all STAC API implementations. The fields of the JSON object can also be used
for a GET endpoint, which are included in the OpenAPI specifications. The GET requests are designed to reflect the same
fields as the POST fields, and are based on WFS 3 requests. It is recommended for implementations to implement both, but
only POST is required.