stac_api_cover

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

Document type: OGC® Community Standard
Document subtype:
Document stage: Draft
Document language: English

The organization listed above has granted the Open Geospatial Consortium (OGC) a nonexclusive, royalty-free, paid up, worldwide license to copy and distribute this document and to modify this document and distribute copies of the modified version under a Creative Commons Attribution 4.0 International License (see below).

The Standard is licensed under the Creative Commons Attribution 4.0 International License (the “License”). You are directed to the License for specific details at: https://creativecommons.org/licenses/by/4.0/deed.en.

Source

The original source for the STAC specification is located on GitHub here:https://github.com/radiantearth/stac-api-spec/tree/release/v1.0.0

STAC API Foundation Specifications

Releases (stable)

Development (unstable)

The main branch in GitHub is used for active development and may be unstable. Implementers should reference one of the release branches above for a stable version of the specification. NOTE: This means that if you are on github.com/radiantearth/stac-api-spec then you are looking at an unreleased, unstable version of the specification. Use the first listed link on releases to read the current released, stable version of the spec.

About

The SpatioTemporal Asset Catalog (STAC) family of specifications aim to standardize the way geospatial asset metadata is structured and queried. A ‘spatiotemporal asset’ is any file that represents information about the Earth captured in a certain space and time. The core STAC specifications live in the GitHub repository radiantearth/stac-spec.

A STAC API is a dynamic version of a SpatioTemporal Asset Catalog. This repository defines the three STAC API foundation specifications – STAC API - Core, STAC API - Features, and STAC API - Item Search – which can be composed with Extensions to define a specific STAC API implementation.

A STAC API can be used to retrieve STAC Catalog, Collection, Item, or STAC API ItemCollection objects from various endpoints. Catalog and Collection objects are JSON, while Item and ItemCollection objects are GeoJSON-compliant entities with foreign members. Typically, a Feature is used when returning a single Item object, and FeatureCollection when multiple Item objects (rather than a JSON array of Item entities).

The API can be implemented in compliance with the OGC API - Features standard (OAFeat is a shorthand). In this case STAC API can be thought of as a specialized Features API to search STAC catalogs, where the features returned are STAC Item objects, that have common properties, links to their assets and geometries that represent the footprints of the geospatial assets.

The specification for STAC API is provided as files that follow the OpenAPI 3.0 specification, rendered online into HTML at https://api.stacspec.org/v1.0.0, in addition to human-readable documentation.

Stability Note

This specification has evolved over the past couple years, and is used in production in a variety of deployments. It is currently in a ‘beta’ state, with no major changes anticipated. As of v1.0.0, we remain fully aligned with OGC API - Features Version 1.0, and we are working to stay aligned as the additional OGC API components mature. This may result in minor changes as things evolve. The STAC API specification follows Semantic Versioning, so once 1.0.0 is reached any breaking change will require the spec to go to 2.0.0.

Maturity Classification

Conformance classes and extensions are meant to evolve to maturity, and thus may be in different states in terms of stability and number of implementations. All extensions must include a maturity classification, so that STAC API spec users can easily get a sense of how much they can count on the extension.

Maturity mostly comes through diverse implementations, so the minimum number of implementations column is the main gating function for an extension to mature. But extension authors can also choose to hold back the maturity advancement if they don’t feel they are yet ready to commit to the less breaking changes of the next level.

A ‘mature’ classification level will likely be added once there are extensions that have been stable for over a year and are used in twenty or more implementations.

Communication

Maturity Classification	Min Impl #	Description	Stability
Proposal	0	An idea put forward by a community member to gather feedback	Not stable - breaking changes almost guaranteed as implementers try out the idea.
Pilot	1	Idea is fleshed out, with examples and a JSON schema, and implemented in one or more catalogs. Additional implementations encouraged to help give feedback	Approaching stability - breaking changes are not anticipated but can easily come from additional feedback
Candidate	3	A number of implementers are using it and are standing behind it as a solid extension. Can generally count on an extension at this maturity level	Mostly stable, breaking changes require a new version and minor changes are unlikely.
Stable	6	Highest current level of maturity. The community of extension maintainers commits to a STAC review process for any changes, which are not made lightly.	Completely stable, all changes require a new version number and review process.
Deprecated	N/A	A previous extension that has likely been superseded by a newer one or did not work out for some reason.	Will not be updated and may be removed in an upcoming major release.

For any questions feel free to jump on our gitter channel or email our google group. The majority of communication about the evolution of the specification takes place in the issue tracker and in pull requests.

In this repository

The Overview document describes all the various parts of the STAC API and how they fit together.

STAC API - Core: The core folder describes the core STAC API specification that enables browsing catalogs and retrieving the API capabilities. This includes the OpenAPI schemas for STAC Item, Catalog and Collection objects.

STAC API - Features: The ogcapi-features folder describes how a STAC API can fully implement OGC API - Features to expose individual items endpoints for search of each STAC collection. It also includes extensions that can be used to further enhance OAFeat.

STAC API - Item Search Specification: The item-search folder contains the Item Search specification, which enables cross-collection search of STAC Item objects at a search endpoint, as well as a number of extensions.

Extensions: The extensions document describes how STAC adds new functionality through extensions. The official list of STAC API Extensions is maintained at stac-api-extensions.github.io.

Fragments: The fragments/ folder contains re-usable building blocks to be used in a STAC API, including common OpenAPI schemas and parameters for behavior like sorting and filtering. Most all of them are compatible with OGC API - Features, and the plan is to fully align the relevant functionality and have it be useful for all OAFeat implementations. OpenAPI YAML documents are provided for each extension with additional documentation and examples provided in a README.

STAC Specification: This repository includes a ‘sub-module’, which is a copy of the STAC specification tagged at the latest stable version. Sub-modules aren’t checked out by default, so to get the directory populated either use git submodule update --init --recursive if you’ve already cloned it, or clone from the start with git clone --recursive git@github.com:radiantearth/stac-api-spec.git.

Implementation Recommendations: Recommendations for implementing a STAC API may be found here. These are mostly concerns that apply to an entire API implementation and are not part of the specification itself.

Contributing

About

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.

STAC API Description

Core

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.

Item Search

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.

Collections and Features

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.

Extensions & Fragments

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.

STAC Core and OGC Versions

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.

Endpoints

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.

Conformance Classes

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.

Conformance Class Table

Example Landing Page

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

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.

{
    "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"
        }
    ]
}

STAC API - Core Specification

Summary

Overview

All STAC API implementations must implement the STAC API - Core conformance class https://api.stacspec.org/v1.0.0/core. This requires a server to return from a root endpoint a valid STAC Catalog “landing page” that also includes a conformsTo attribute with a string array value. Any API implementing this is considered a minimal, valid STAC API.

Core

The root of a STAC API is the Landing Page, which is a STAC Catalog object with additional fields. This resource is the starting point to determine what behaviors the API supports via the conformsTo array and the URIs of resources via link relations. Support for this type of behavior in a web API is known as Hypermedia as the Engine of Application State (HATEOAS). A hypermedia-driven web API provides a robust, consistent, and flexible mechanism for interacting with remote resources. STAC API relies heavily on hypermedia for API resource discovery and navigation.

In a STAC API, the root endpoint (Landing Page) has the following characteristics:

Note the conformsTo array follows the same structure of the OGC API - Features declaration of conformance classes, except it is part of the landing page instead of in the JSON response from the /conformance endpoint. This is different from how the OGC API advertises conformance, as STAC feels it is important for clients to understand conformance from a single request to the landing page. Implementers who implement the OGC API - Features and/or STAC API - Features conformance classes must also implement the /conformance endpoint.

The scope of the conformance classes declared in the conformsTo field and the /conformance endpoint are limited to the STAC API Catalog that declares them. A STAC API Catalog may link to sub-catalogs within it via child links that declare different conformance classes. This is useful when an entire catalog cannot be searched against to support the STAC API - Item Search conformance class, perhaps because it uses multiple databases to store items, but sub-catalogs whose items are all in one database can support search.

Link Relations

The STAC definition of Link does not require the type field, but it is STRONGLY RECOMMENDED that this field exists. If the target of a Link’s type is unknown, type SHOULD be set to application/octet-stream or text/plain.

rel	href	Media Type	From	Description
`root`	`/`	application/json	STAC API - Core	REQUIRED The root URI
`self`	`/`	application/json	OAFeat	REQUIRED Self reference, same as root URI
`service-desc`	`/api`	various	OAFeat	REQUIRED The service description in a machine-readable format
`service-doc`	`/api.html`	text/html	OAFeat	A human-consumable service description. The path for this endpoint is only recommended to be `/api.html`, but may be another path.
`child`	various	application/json	STAC API - Core	The child STAC Catalogs & Collections.
`item`	various	application/geo+json	STAC API - Core	The child STAC Items.

The path for the service-desc endpoint is recommended to be /api, but may be another path. Recommended to be OpenAPI 3.0 or 3.1 with media types application/vnd.oai.openapi (YAML), application/vnd.oai.openapi+json;version=3.0 (3.0 JSON), or application/vnd.oai.openapi+json;version=3.1 (3.1 JSON).

A service-doc endpoint is recommended, but not required. This commonly returns an HTML page, for example, in the form of Redoc interactive API , but any format is allowed. The Link type field should correspond to whatever format or formats are supported by this endpoint, e.g., text/html.

Additionally, child relations may exist to child Catalogs and Collections and item relations to Items. These relations form a directed graph that enables traversal from a root catalog or collection to items.

While it is valid to have item links from the landing page, most STAC API implementations serve large numbers of features, so they will typically use several layers of intermediate child links to sub-catalogs and collections before getting to Item objects. These relations form a directed graph of Catalogs and Collections, where interior nodes contain child relations, and the penultimate nodes will be Catalogs with item relations to individual Items as leaf nodes.

child link relations may point to another STAC Catalog that also acts as a STAC API root, which can support search over only a sub-catalog. This is useful for very large or federated catalogs that cannot support searching over the entire catalog, but can support searching over individual sub-catalogs within it.

Note that there is a different link relation items (plural) used by the STAC API - Features conformance class that links from a collection resource (at the /collections/{collectionId} endpoint) to the items in that collection (at the /collections/{collectionId}/items endpoint). Both of these endpoints are derived from OGC API - Features.

Endpoints

This conformance class also requires for the endpoints in the STAC API - Core conformance class to be implemented.

Endpoint	Media Type	Returns	Description
`/`	application/json	Catalog	Landing page, links to API capabilities
`/api`	various	any	The service description of the service from the `service-desc` link `rel`. The path is only recommended to be `/api`, and is at the discretion of the implementer.

The service description endpoint may return any specification format. It is recommended to use OpenAPI 3.0 or 3.1 with media types application/vnd.oai.openapi (YAML), application/vnd.oai.openapi+json;version=3.0 (3.0 JSON), or application/vnd.oai.openapi+json;version=3.1 (3.1 JSON). Whichever format or formats are used, the link with relation service-desc must have a type field that matches an Accept header value to which the service responds, and the Content-Type header in the response should contain the same media type. If the OpenAPI 3.0 format is used, the conformance class http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30 should be advertised. All service descriptions provided as part of the STAC API spec use OpenAPI 3.0 YAML format, and can easily be used to return either YAML or JSON from this endpoint. OAFeat does not currently define a conformance class for OpenAPI 3.1, but may in the future.

Example Landing Page for STAC API - Core

This JSON is what would be expected from an API that only implements STAC API - Core. It is a valid STAC Catalog with additional Links and a conformsTo attribute. In practice, most APIs will also implement other conformance classes, and those will be reflected in the links and conformsTo attribute. A more typical Landing Page example is in the overview document.

This particular catalog provides both the ability to browse down to child Catalog objects through its child links, and also provides the search endpoint to be able to search across items in its collections. Note that some of those links are not required and other servers may provide different conformance classes and a different set of links.

{
    "stac_version": "1.0.0",
    "id": "example-stac",
    "title": "A simple STAC API Example",
    "description": "This Catalog aims to demonstrate a simple landing page",
    "type": "Catalog",
    "conformsTo" : [
        "https://api.stacspec.org/v1.0.0/core"
    ],
    "links": [
        {
            "rel": "self",
            "type": "application/json",
            "href": "https://stac-api.example.com"
        },
        {
            "rel": "root",
            "type": "application/json",
            "href": "https://stac-api.example.com"
        },
        {
            "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": "child",
            "type": "application/json",
            "href": "https://stac-api.example.com/catalogs/sentinel-2"
        },
        {
            "rel": "child",
            "type": "application/json",
            "href": "https://stac-api.example.com/catalogs/landsat-8"
        }
    ]
}

Extensions

STAC API - Collections and Features Specification

Summary

Overview

The STAC API - Collections and Features specification extends the OGC API - Features - Part 1: Core (OAFeat) specification. OAFeat allows returning any content type from its endpoints, whereas STAC API - Features requires support for returning STAC Item and STAC Collection entities. As these entities are also GeoJSON types, the GeoJSON conformance class of OGC API - Features is supported (http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson).

Conformance Classes

While OAFeat defines a single conformance class for its endpoints, STAC API divides these behaviors into two conformance classes – Collections and Features. The STAC API - Features (https://api.stacspec.org/v1.0.0/ogcapi-features) conformance class includes and extends the behavior of OAFeat, while the STAC API - Collections (https://api.stacspec.org/v1.0.0/collections) conformance class is the subset of Features that pertains only to Collections.

STAC API - Features

STAC API - Collections

The STAC API - Collections (https://api.stacspec.org/v1.0.0/collections) conformance class requires only the subset of the behavior of Features that relates to Collections.

This subset of behavior is useful in conjunction with the STAC API - Item Search conformance class to allow the description of STAC Collections without needing to implement the entire STAC API - Features conformance class.

OGC API - Features - Part 1: Core

OGC API - Features - Part 1: GeoJSON

OGC API - Features - Part 1: OpenAPI 3.0

Link Relations

These conformance classes also requires implementation of the link relations in the STAC API - Core conformance class.

Landing Page (/)

Collections (/collections)

rel	href	Media Type	From	Description
`conformance`	`/conformance`	application/json	OAFeat	REQUIRED Conformance URI
`data`	`/collections`	application/json	OAFeat	REQUIRED List of Collections

The following Link relations are defined for the /collections endpoint response.

Collection (/collections/{collectionId})

rel	href	Media Type	From	Description
`root`	`/`	application/json	STAC API - Features, STAC API - Collections	REQUIRED The root URI
`self`	`/collections`	application/json	OAFeat	REQUIRED Self reference

The following Link relations are defined for the Collection object returned from the /collections/{collectionId} endpoint.

rel	href	Media Type	From	Description
`root`	`/`	application/json	STAC API - Features, STAC API - Collections	REQUIRED The root URI
`self`	`/collections/{collectionId}`	application/json	OAFeat	REQUIRED Self reference
`parent`	`/`	application/json	STAC Collection	Parent reference, usually the root Catalog
`canonical`	various	various	STAC API - Core	Provides the preferred paths to get to STAC Collection and Item objects, if they differ from the URL that was used to retrieve the STAC object and thus duplicate other content. This can be useful in federated catalogs that present metadata that has a different location than the source metadata.

Usually, the self link in a Collection must link to the same URL that was used to request it. However, implementations may choose to have the canonical location of the Collection be elsewhere. If this is done, it is recommended to include a rel of canonical to that location.

Note that the parent link for a Collection should be point to the parent Catalog (such as the root Catalog, /) or Collection of that Collection, rather than the API sub-path of /collections.

Collection Items (/collections/{collectionId}/items)

The following Link relations are defined for the ItemCollection object returned from the /collections/{collectionId}/items endpoint.

Items (/collections/{collectionId}/items/{itemId})

rel	href	Media Type	From	Description
`root`	`/`	application/json	STAC API - Features	REQUIRED The root URI
`self`	`/collections/{collectionId}/items`	application/geo+json	OAFeat	REQUIRED Self reference
`collection`	`/collections/{collectionId}`	application/json	OAFeat	REQUIRED Collection reference

The following Link relations are defined for the Item object returned from the /collections/{collectionId}/items/{itemId} endpoint.

rel	href	Media Type	From	Description
`root`	`/`	application/json	STAC API - Features	REQUIRED The root URI
`self`	`/collections/{collectionId}/items/{itemId}`	application/geo+json	OAFeat	REQUIRED Self reference
`collection`	`/collections/{collectionId}`	application/json	STAC Item	REQUIRED The containing Collection
`parent`	`/collections/{collectionId}`	application/json	STAC Item	Parent reference, usually the containing Collection

The parent link for an Item may point to a Collection or a Catalog. The collection link for an Item will always point to the containing Collection. Links to a Collection must point to the /collections/{collectionId} endpoint, rather than the API sub-path of /collections/{collectionId}/items/.

Endpoints

This conformance class also requires for the endpoints in the STAC API - Core conformance class to be implemented.

The OGC API - Features endpoints are shown below, with details provided in the OpenAPI specifications for Features or Collections.

Endpoint	Returns	Media Type	Description
`/collections`	application/json	JSON	Object containing an array of Collection objects in the Catalog, and Link relations
`/collections/{collectionId}`	application/json	Collection	Returns single Collection JSON
`/collections/{collectionId}/items`	application/geo+json	ItemCollection	GeoJSON FeatureCollection-conformant entity of Item objects in collection
`/collections/{collectionId}/items/{featureId}`	application/geo+json	Item	Returns single Item (GeoJSON Feature)

The OGC API - Features is a standard API that represents collections of geospatial data. It defines a RESTful interface to query geospatial data, with GeoJSON as a main return type. With OAFeat you can return any Feature, which is a geometry plus any number of properties. The core STAC Item spec enhances the core Feature with additional requirements and options to enable cataloging of spatiotemporal ‘assets’ like satellite imagery.

OAFeat also defines the concept of a Collection, which contains Features. In OAFeat, a Collection is a set of data that can be queried (7.11), and each describes basic information about the geospatial dataset, like its name and description, as well as the spatial and temporal extents of all the data contained. A STAC Collection contains this same information, along with other STAC-specific fields to provide additional metadata for searching spatiotemporal assets, and thus are compliant with both OAFeat Collection and STAC Collection, and are returned from the /collections/{collectionId} endpoint.

In OAFeat, Features are the individual records within a Collection and are usually provided in GeoJSON format. STAC Item objects are compliant with the OAFeat Features GeoJSON requirements class, and are returned from the /collections/{collectionId}/items/{itemId} endpoint. The return of other encodings (html, gml) is outside the scope of STAC API, as the STAC Item is specified in GeoJSON.

A typical OAFeat will have multiple collections. Simple search for items within a collection can be done with the resource endpoint GET /collections/{collectionId}/items. This endpoint must be exposed via a link in the individual collection’s endpoint with rel=items, as shown in the Example Landing Page diagram. Note that this relation is items, which is distinct from the item relation defined in STAC for linking to a single Item. The part of the API implementing OAFeat will usually not use item relations directly, but instead rely on the collection resource linking to a paginated endpoint returning items through a link relation items, e.g., /collections/{collectionId} has a link with relation items linking to /collections/{collectionId}/items. However, static catalogs and other parts of the API may contain item relations.

It is recommended to have each OAFeat Collection correspond to a STAC Collection, and the /collections/{collectionId}/items endpoint can be used as a single collection search. Implementations may optionally provide support for the full superset of STAC API query parameters to the /collections/{collectionId}/items endpoint, where the collection ID in the path is equivalent to providing that single value in the `Collections* query parameter in STAC API.

Implementing OAFeat enables a wider range of clients to access the API’s STAC Item objects, as it is a more widely implemented protocol than STAC.

Item Pagination

OAFeat supports paging through hypermedia links for the Items resource (/collections/{collectionId}/items). Since only GET requests are allowed for this endpoint, it is possible to provide a Link with rel type next and the href of the full URL of the next page of results. This link href must contain any URL parameters that are necessary for the implementation to understand how to provide the next page of results, e.g., the query parameters page, next, or token and any additional filter parameters if given and required. For example, the links array will have an object like:

    "links": [
        {
            "rel": "next",
            "type": "application/geo+json",
            "href": "https://stac-api.example.com/collections/my_collection/items?page=2"
        }
    ]

The href may contain any arbitrary URL parameter, which is implementation-specific:

In addition to supporting query parameters in the URL value of the href field, STAC has extended the Link object with additional fields to support more complex HTTP requests. These include method to specify an HTTP method GET or POST, headers to add HTTP headers in the request, and body with either the entire body for the request or only the body fields that must be changed from the previous request, as determined by the merge field. These fields are described in detail in the Item Search spec.

Implementations may also add link relations prev, first, and last. Most API implementations should be able to support first, though last may be infeasible to implement in some data stores.

Collection Pagination

OAFeat does not define a specific mechanism for how clients may access all collections from servers with many collections. STAC API - Features adds support for this with pagination (similar to the Item pagination mechanism) through hypermedia links for the Collections resource (/collections). This mechanism aligns with pagination of collections in the OGC API - Common - Part 2: Geospatial Data specification. With this, a link with relation next is included in the links array, and this is used to navigate to the next page of Collection objects. The specific query parameter used for paging is implementation specific and not defined by STAC API. For example, an implementation may take a parameter (e.g., page) indicating the numeric page of results, a base64-encoded value indicating the last result returned for the current page (e.g., search_after as in Elasticsearch), or a cursor token representing backend state.

In our simple example of numerical pages, the response for page=3 would have a links array containing these two Links indicating the URLs for the next (page=4) and previous (page=2) pages:

{
    "links": [
    {
        "rel": "prev",
        "type": "application/json",
        "href": "https://stac-api.example.com/collections?page=2"
    },
    {
        "rel": "next",
        "type": "application/json",
        "href": "https://stac-api.example.com/collections?page=4"
    }
    ]
}

Implementations may also add link relations prev, first, and last. Most API implementations should be able to support first, though last may be infeasible to implement in some data stores.

Examples

Note that the OAFeat endpoints only allow HTTP GET. HTTP POST requests are not supported. If POST is required, it is recommended to use STAC Item Search, as it can be constrained to a single collection to act the same as an OAFeat items endpoint.

Request all the data in mycollection that is in New Zealand at anytime on January 1st, 2019:

Request 10 results from the data in mycollection from between January 1st (inclusive) and April 1st, 2019 (exclusive):

Example Landing Page

This JSON is what would be expected from an api that implements only STAC API - Core and STAC API - Features. In practice, most APIs will also implement other conformance classes, and those will be reflected in the links and conformsTo fields. A more typical Landing Page example is in the overview document.

{
    "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/ogcapi-features",
        "https://api.stacspec.org/v1.0.0/collections",
        "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"
        }
    ]
}

Example Collection Endpoint

The landing page data relation points to an endpoint to retrieve all collections. Each collection then has a link relation to its items resource through the link with a rel value items. Note here that, unlike as is typical with a static STAC Collection, there are no links here with rel value item.

{
  "id": "aster-l1t",
  "type": "Collection",
  "title": "ASTER L1T",
  "links": [
    {
      "rel": "items",
      "type": "application/geo+json",
      "href": "https://stac-api.example.com/collections/aster-l1t/items"
    },
    {
      "rel": "parent",
      "type": "application/json",
      "href": "https://stac-api.example.com"
    },
    {
      "rel": "root",
      "type": "application/json",
      "href": "https://stac-api.example.com"
    },
    {
      "rel": "self",
      "type": "application/json",
      "href": "https://stac-api.example.com/collections/aster-l1t"
    }
  ]
}

Extensions

STAC API - Item Search

Summary

Overview

The STAC API - Item Search specification defines the STAC API - Item Search conformance class (https://api.stacspec.org/v1.0.0/item-search), which provides the ability to search for STAC Item objects across collections. It retrieves a group of Item objects that match the provided parameters, wrapped in an ItemCollection (which is a valid GeoJSON FeatureCollection that contains STAC Item objects). Several core query parameters are defined by OGC API - Features, with a few additions specified in this document.

The Item Search endpoint intentionally defines only a limited group of operations. It is expected that most behavior will be defined in Extensions. These extensions can be composed by an implementer to cover only the set of functionality the implementer requires. For example, the query capability defined by Item Search is limited, and only adds cross-collection and spatial intersects query operators to the capabilities already defined by OAFeat. For example, the Query Extension and Filter Extension provide a more expressive set of operators.

Implementing GET /search is required, POST /search is optional, but recommended.

Link Relations

This conformance class also requires implementation of the link relations in the STAC API - Core conformance class.

rel	href	Media Type	From	Description
`search`	`/search`	application/geo+json	STAC API - Item Search	REQUIRED URI for the Search endpoint

This search link relation must have a type of application/geo+json. If no method attribute is specified, it is assumed to represent a GET request. If the server supports both GET and POST requests, two links should be included, one with a method of GET one with a method of POST.

Other links with relation search may be included that advertise other content types the server may respond with, but these other types are not part of the STAC API requirements.

Endpoints

rel	href	From	Description
`root`	`/`	STAC API - Item Search	REQUIRED The root URI

This conformance class also requires for the endpoints in the STAC API - Core conformance class to be implemented.

Query Parameters and Fields

The following list of parameters is used to narrow search queries. They can all be represented as query string parameters in a GET request, or as JSON entity fields in a POST request. For filters that represent a set of values, query parameters must use comma-separated string values with no enclosing brackets ([ or ]) and no whitespace between values, and JSON entity attributes must use JSON Arrays.

Query Examples

Endpoint	Returns	Media Type	From	Description
`/search`	Item Collection	application/geo+json	STAC API - Item Search	Search endpoint

{
    "collections": ["landsat8","sentinel"],
    "bbox": [-10.415,36.066,3.779,44.213],
    "limit": 200,
    "datetime": "2017-05-05T00:00:00Z"
}

Query Parameter Table

The core parameters for STAC search are defined by OAFeat, and STAC adds a few parameters for convenience.

Parameter	Type	Source API	Description
limit	integer	OAFeat	The maximum number of results to return (page size).
bbox	[number]	OAFeat	Requested bounding box.
datetime	string	OAFeat	Single date+time, or a range (‘/’ separator), formatted to RFC 3339, section 5.6. Use double dots `..` for open date ranges.
intersects	GeoJSON Geometry	STAC	Searches items by performing intersection between their geometry and provided GeoJSON geometry. All GeoJSON geometry types must be supported.
ids	[string]	STAC	Array of Item ids to return.
collections	[string]	STAC	Array of one or more Collection IDs that each matching Item must be in.

limit The limit parameter follows the same semantics of the OAFeat Item resource limit parameter. The value is a suggestion to the server as to the maximum number of Item objects the client would prefer in the response. The server may return fewer Item objects, but must not return more. The OpenAPI specification defines the default and maximum values for this parameter. The base specifications define these with a default of 10 and a maximum of 10000, but implementers may choose other values to advertise through their service-desc endpoint. If the limit parameter value is greater than the advertised maximum limit, the server must act as if the request were for the maximum and not return an error.

datetime The datetime parameter use the same allowed values as the OAF datetime parameter. This allows for either a single RFC 3339 datetime or an open or closed interval that also uses RFC 3339 datetimes. Additional details about this parameter can be found in the Implementation Recommendations.

Only one of either intersects or bbox may be specified. If both are specified, a 400 Bad Request status code must be returned.

bbox Represented using either 2D or 3D geometries. The length of the array must be 2*n where n is the number of dimensions. The array contains all axes of the southwesterly most extent followed by all axes of the northeasterly most extent specified in Longitude/Latitude or Longitude/Latitude/Elevation based on WGS 84. When using 3D geometries, the elevation of the southwesterly most extent is the minimum elevation in meters and the elevation of the northeasterly most extent is the maximum. When filtering with a 3D bbox over Items with 2D geometries, it is assumed that the 2D geometries are at elevation 0. Degenerate bboxes that form a point or line must be supported.

intersects It is at the discretion of the implementation to reject semantically-invalid GeoJSON objects, e.g., a self-intersecting Polygon or a LineString with zero-length segments. These should result in a 400 Bad Request status code and a specific error message, rather than a 500 Server Error and generic or database-level error message.

Response

The response to a request (GET or POST) to the search endpoint must always be an ItemCollection object - a valid GeoJSON FeatureCollection that consists entirely of STAC Item objects.

Pagination

OGC API supports paging through hypermedia links and STAC follows the same pattern for the cross collection search. For GET requests, a link with rel type next is supplied. This link may contain any URL parameter that is necessary for the implementation to understand how to provide the next page of results, eg: page, next, token, etc. The parameter name is defined by the implementor and is not necessarily part of the API specification. For example:

{
    "type": "FeatureCollection",
    "features": [],
    "links": [
        {
            "rel": "next",
            "href": "https://stac-api.example.com/search?page=3",
            "type": "application/geo+json"

        },
        {
            "rel": "prev",
            "href": "https://stac-api.example.com/search?page=1",
            "type": "application/geo+json"
        },
        {
            "rel": "root",
            "href": "https://stac-api.example.com/",
            "type": "application/json"
        }
    ]
}

Implementations may also add link relations prev, first, and last, though these are not required and may be infeasible to implement in some data stores.

OAFeat does not support POST requests for searches, however the STAC API spec does. Hypermedia links are not designed for anything other than GET requests, so providing a next link for a POST search request becomes problematic. STAC has decided to extend the Link object to support additional fields that provide hints to the client as to how it must execute a subsequent request for the next page of results.

The following fields have been added to the Link object specification for the API spec:

The implementor has the freedom to decide exactly how to apply these extended fields for their particular pagination mechanism. The same freedom that exists for GET requests, where the actual URL parameter used to defined the next page of results is purely up to the implementor and not defined in the API spec, if the implementor decides to use headers, there are no specific or required header names defined in the specification. Implementors may use any names or fields of their choosing. Pagination can be provided solely through header values, solely through body values, or through some combination.

Parameter	Type	Description
method	string	The HTTP method of the request, usually `GET` or `POST`. Defaults to `GET`
headers	object	A dictionary of header values that must be included in the next request
body	object	A JSON object containing fields/values that must be included in the body of the next request
merge	boolean	If `true`, the headers/body fields in the `next` link must be merged into the original request and be sent combined in the next request. Defaults to `false`

To avoid returning the entire original request body in a POST response which may be arbitrarily large, the merge property can be specified. This indicates that the client must send the same post body that it sent in the original request, but with the specified headers/body values merged in. This allows servers to indicate what needs to change to get to the next page without mirroring the entire query structure back to the client.

HTTP Request Methods and Content Types

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”). This section describes how these are used with the /search endpoint.

GET

Required: STAC’s cross-collection /search requires GET queries for all implementations, following OAFeat’s precedent of making GET required (it only specifies GET so far).

POST

Recommended STAC /search is strongly recommended to implement POST Content-Type: application/json, where the content body is a JSON object representing a query and filter, as defined in this document.

It is recommended that clients use POST for querying (if the STAC API supports it), especially when using the intersects query parameter, for two reasons:

STAC API extensions allow for more sophisticated searching, such as the ability to sort, select which fields you want returned, and searching on specific Item properties.

PUT / PATCH / DELETE

The other HTTP verbs are not supported in STAC Item Search. The Transaction Extension does implement them, for STAC and OAFeat implementations that want to enable writing and deleting items.

Example Landing Page for STAC API - Item Search

This JSON is what would be expected from an api that only implements STAC API - Item Search. In practice, most APIs will also implement other conformance classes, and those will be reflected in the links and conformsTo fields. A more typical Landing Page example is in the overview document.

{
    "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/item-search"
    ],
    "links": [
        {
            "rel": "self",
            "type": "application/json",
            "href": "https://stac-api.example.com"
        },
        {
            "rel": "root",
            "type": "application/json",
            "href": "https://stac-api.example.com"
        },
        {
            "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": "search",
            "type": "application/geo+json",
            "href": "https://stac-api.example.com/search",
            "method": "GET"
        },
        {
            "rel": "search",
            "type": "application/geo+json",
            "href": "https://stac-api.example.com/search",
            "method": "POST"
        }
    ]
}

Extensions

STAC API Extensions

STAC API aims to define a core of functionality, with richer capabilities enabled by extensions. The list of STAC API Extensions is maintained at https://stac-api-extensions.github.io.

All extensions must include a maturity classification, so that STAC API specification users can easily get a sense of how much they can count on the extension.

Extensions and Conformance

Each extension has its own conformance class, which is specified with one or more conformance URIs that are defined for the extension. These must be listed in the conformsTo JSON of the Landing Page, as specified by STAC API - Core, to let clients know that they can use the functionality.

A number of extensions define functionality that could be used easily in a number of endpoints, such as additional parameters for search through either STAC API - Item Search or STAC API - Features.

Creating new extensions

Creating new extensions requires creating an OpenAPI fragment to define it, along with a README markdown file that gives an overview of the functionality. In the README, a conformance URI should be provided, so clients can use it to tell if a service has the indicated functionality. It is also recommended to note the ‘extension maturity’, as defined above, so others can know how widely it is used.

The new extension can live anywhere online, with a recommendation of using a GitHub repository to be able to track changes. The first step in sharing the extension is to add it to the official list, as described above. If it is of something that the wider community may be interested in, then it may be added to the stac-api-extensions GitHub organization.

STAC API - ItemCollection Fragment

This document explains the structure and content of a SpatioTemporal Asset Catalog (STAC) ItemCollection. An ItemCollection is a GeoJSON FeatureCollection that is augmented with foreign members relevant to a STAC entity.

Similarly to the relationship between a GeoJSON Feature and a STAC Item, a STAC ItemCollection must be a valid GeoJSON FeatureCollection to allow interoperability with existing tools that support GeoJSON.

Item objects are represented in JSON format and are very flexible. Any JSON object that contains all the required fields is a valid STAC ItemCollection.

ItemCollection fields

This object describes a STAC ItemCollection. The fields type and features are inherited from GeoJSON FeatureCollection.

Field Name	Type	Description
type	string	REQUIRED. Always “FeatureCollection” to provide compatibility with GeoJSON.
features	[STAC Item]	REQUIRED. A possibly-empty array of Item objects.
links	[Link Object]	An array of Links related to this ItemCollection.
numberMatched	integer	The number of Items that meet the selection parameters, possibly estimated.
numberReturned	integer	The number of Items in the `features` array.