- STAC API - Collections and Features Specification
- OpenAPI specifications:
- Conformance Class URIs:
- https://api.stacspec.org/v1.0.0/ogcapi-features - Features
- https://api.stacspec.org/v1.0.0/collections - Collections
- Maturity Classification: Candidate
- Dependencies:
- STAC API - Core
- OGC API - Features uses all the OGC API - Features openapi fragments to describe returning STAC Item objects.
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).
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.
The STAC API - Features (https://api.stacspec.org/v1.0.0/ogcapi-features) conformance class encompasses all of the behavior described in this specification, as derived from OAFeat.
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 is:
- the
datalink relation on the landing page - the
/collectionsand/collections/{collection_id}endpoints
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.
A STAC API implementation that conforms to STAC API - Features (https://api.stacspec.org/v1.0.0/ogcapi-features) also conforms to OGC API - Features - Part 1 Requirements Class Core conformance class (http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core). This conformance class should be advertised to OAFeat clients so they will also work with the STAC API.
A STAC API implementation that conforms to STAC API - Features also conforms to OGC API - Features - Part 1 Requirements Class GeoJSON (http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson) This conformance class should be advertised to OAFeat clients so they will know of the support for GeoJSON.
If OpenAPI 3.0 is used for the endpoint referenced by the service-desc link relation in the landing page defined
by STAC API - Core, the
OGC API - Features - Part 1 Requirements Class OpenAPI 3.0
(http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30) can be advertised.
These conformance classes also requires implementation of the link relations in the STAC API - Core conformance class.
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.
The following Link relations are defined for the Landing Page (root).
| 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.
| 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.
The following Link relations are defined for the ItemCollection object returned from the /collections/{collectionId}/items endpoint.
| 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/.
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.
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:
https://stac-api.example.com/collections/my_collection/items?page=2https://stac-api.example.com/collections/my_collection/items?next=8a35eba9chttps://stac-api.example.com/collections/my_collection/items?token=f32890a0bdb09ac3
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.
See the paging examples for additional insight.
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"
}
]
}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.
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:
GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89
Request 100 results in mycollection from New Zealand:
GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&limit=100
Request all the data in mycollection that is in New Zealand at anytime on January 1st, 2019:
GET /collections/mycollection/items?bbox=160.6,-55.95,-170,-25.89&datetime=2019-01-01T00:00:00Z/2019-01-01T23:59:59Z
Request 10 results from the data in mycollection from between January 1st (inclusive) and April 1st, 2019 (exclusive):
GET /collections/mycollection/items?datetime=2019-01-01T00:00:00Z/2019-03-31T23:59:59Z&limit=10
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"
}
]
}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.
https://stac-api.example.com/collections/aster-l1t
{
"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"
}
]
}STAC API Extensions can be found at stac-api-extensions.github.io.