The STAC API is intended to be a superset of the WFS 3 API specification. STAC API currently bases on WFS 3 draft.2, also more recently known as OGC API - Features - Part 1: Core, v1.0.0-draft.2.
The Web Feature Service is a standard API that represents collections of geospatial data. The Web Feature Service 3.0 API, currently under development, is the latest iteration of that standard. WFS 3 defines the RESTful interface to query geospatial data, with GeoJSON as a main return type. With WFS you can return any Feature, which is a geometry plus any number of properties. In the STAC specification an Item is a Feature, with additional required fields for datetime and assets. WFS also defines the concept of a Collection, which contains Features. A STAC Collection aligns with (and extends slightly) a WFS 3 Collection; it contains Items.
In WFS 3 Collections are the sets 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. STAC collections contain this same information, along with other STAC specific fields and thus are compliant with both WFS Collections and STAC Collections and is returned from the /collections/{collection_id} endpoint.
In WFS 3 Features are the individual records within a Collection and are provided in GeoJSON format. STAC Items are analogous to WFS 3 Features, are in GeoJSON, and are returned from the /collections/{collection_id}/items/{item_id} endpoint.
The WFS 3 and STAC APIs follow a RESTful model. A core principal of this is the use of HTTP Request Methods (verbs) and the Content-Type header to drive behavior. This section describes how these are used in the WFS 3 and STAC endpoints.
- Required GET (both WFS 3 and STAC)
- Recommended POST
Content-Type: application/x-www-form-urlencodedwith the corresponding content body format. - Recommended POST
Content-Type: multipart/form-datawith the corresponding content body format. - Optional STAC endpoint /stac/search only POST
Content-Type: application/json, where the content body is a JSON object representing a filter, as defined in the STAC API OpenAPI specification document. - Prohibited WFS 3 endpoints only POST
Content-Type: application/json, where the content body is a JSON object representing a filter. This is prohibited due to conflict with the Transaction Extension, which defines a POSTContent-Type: application/jsonoperation to create an Item.
The core WFS 3 endpoints are shown below, with details provided in an OpenAPI specification document.
| Endpoint | Returns | Description |
|---|---|---|
| / | JSON | Landing page, links to API capabilities |
| /conformance | JSON | Info about standards to which the API conforms |
| /collections | [Collection] | List of Collections contained in the catalog |
| /collections/{collectionId} | Collection | Returns single Collection JSON |
| /collections/{collectionId}/items | ItemCollection | GeoJSON FeatureCollection-conformant entity of Items in collection |
| /collections/{collectionId}/items/{featureId} | Item | Returns single Item (GeoJSON Feature) |
The /collections/{collection_id}/items endpoint accepts parameters for filtering the results (also called filters).
Items in the collection should match all filters to be returned when querying. This implies a logical AND operation. If an OR operation is needed, it should be specified through an extension filter.
STAC provides some additional endpoints for the root Catalog itself, as well as the capability to search the Catalog. Note that a STAC API does not need to implement WFS 3, in which case it would only support the endpoints given below. See the OpenAPI specification document.
| Endpoint | Returns | Description |
|---|---|---|
| /stac | Catalog | Root catalog |
| /stac/search | ItemCollection | Retrieves a group of Items matching the provided search predicates, probably containing search metadata from the search extension |
The /stac endpoint should function as a complete Catalog representation of all the data contained in the API and linked to in some way from root through Collections and Items.
The /stac/search endpoint is similar to the items endpoint in WFS3 in that it accepts parameters for filtering, however it performs the filtering across all collections. The parameters accepted are the same as the Filter Parameters above, however the extensions also provide advanced querying parameters.
If the /stac/search endpoint is implemented, it is required to add a link with the rel type set to search to the links array in GET /stac that refers to the search endpoint in the href property.
Unless otherwise noted by Path-only, these filters are passed as query string parameters, form parameters, or JSON entity fields. For filters that represent a set of values, query and form parameters should use comma-separated string values and JSON entity attributes should use JSON Arrays.
| Parameter | Type | APIs | Description |
|---|---|---|---|
| collectionId | [string] | WFS3 | Path-only Single Collection ID to include in the search for items. Only Items in one of the provided Collection will be searched |
| limit | integer | WFS3, STAC | The maximum number of results to return (page size). Defaults to 10 |
| bbox | [number] | WFS3, STAC | Requested bounding box. 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. |
| datetime | string | WFS3, STAC | Single date+time, or a range ('/' seperator), 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. |
| next | string | STAC | The token to retrieve the next set of results, e.g., offset, page, continuation token |
| ids | [string] | Array of Item ids to return. All other filter parameters that further restrict the number of search results (except next and limit) are ignored |
|
| collections | [string] | STAC | Array of Collection IDs to include in the search for items. Only Items in one of the provided Collections will be searched |
Only one of either intersects or bbox should be specified. If both are specified, a 400 Bad Request response should be returned.
Additionally, there are several reserved parameters over STAC search that have no meaning in the base STAC API specification, but which are reserved exclusively for the use of API Extensions. API implementations are free to add additional implementation-specific parameters, but they MUST NOT use following parameters unless implementing the syntax and semantics of an API Extension attached to that parameter. If no API Extension for that parameter is implemented by an API, then if that parameter has a non-empty value in the request a 400 Bad Request status code must be returned.
These parameters and fields are reserved for the Fields extension.
| Parameter | Type | APIs | Description |
|---|---|---|---|
| fields | string | [Field] | Placeholder parameter for API Fields Extension. |
These parameters and fields are reserved for the Sort extension.
| Parameter | Type | APIs | Description |
|---|---|---|---|
| sort | string | [Sort] | Placeholder parameter for API Sort Extension. |
These parameters and fields are reserved for query extensions.
All Extensions should use attribute names qualified from the root of Item, rather than Item Properties.
| Parameter | Type | APIs | Description |
|---|---|---|---|
| query | string | QueryFilter | Placeholder parameter for API Query Extension query value. |
query Represents a query in the query language.