Catalog API
Sentinel Hub Catalog is an API implementing the STAC Specification to describe geospatial information about different data used inside Sentinel Hub.
API Reference
The API Reference for Sentinel HUB Catalog is available as OpenAPI description.
Simple search request for Sentinel 1 GRD products inside the bounding box (the coordinate reference system of the values is WGS84 longitude/latitude), available on 10th December 2019.
curl -X POST 'services.sentinel-hub.com/api/v1/catalog/search' \--header 'Authorization: Bearer <your access token>' \--header 'Content-Type: application/json' \--data-raw '{"bbox": [13,45,14,46],"datetime": "2019-12-10T00:00:00Z/2019-12-10T23:59:59Z","collections": ["sentinel-1-grd"],"limit": 5}'
Authentication
Authentication for the Catalog API works completely the same as authentication for the process API, see Authentication chapter.
Pagination
Executing the request specified above returns search context fields at the end of response looking like:
{"context": {"next": 5,"limit": 5,"returned": 5}}
The presence of next
attribute indicates there is more data available for this query, but the server chose to not return it since the limit
specified was 5
(if limit
is not specified default value is 10
). To query next page of items our request need to include this next
attribute with its value in the query like:
curl -X POST 'services.sentinel-hub.com/api/v1/catalog/search' \--header 'Authorization: Bearer <your access token>' \--header 'Content-Type: application/json' \--data-raw '{"bbox": [13,45,14,46],"datetime": "2019-12-10T00:00:00Z/2019-12-10T23:59:59Z","collections": ["sentinel-1-grd"],"limit": 5,"next": 5}'
Response now includes next page of items, in this case there is no next
token in context
meaning no more items exist for this query.
Extensions
Query
The search endpoint by default only accepts some parameters described in [OpenAPI](link to post search in apireference). The Query extension enables users to specify additional parameter to filter on while searching through data.
The syntax for query
filter is:
{"query": {"<property_name>": {"<operator>": <value>}}}
Available operators are eq
, neq
, lt
, lte
, gt
, gte
. But be careful - different colllections have different properties available that can be used as propery inside query filter. Information describing this is available inside the documentation for each specific collection (ex. Sentinel 1 GRD).
Fields
By default the search endpoint returns all available attribues of each item. Fields extension provides a way to the client to specify which attributes should not be part of the output, making it easy for the client to not have to deal with unnecessary data.
Syntax for the fields
is:
{"fields": {"include": [<list_of_attributes_to_include>],"exclude": [<list_of_properties_to_exclude]}}
Include/Exclude behaviour
- When no
fields
attribute is specified in the request all available attributes will be included in the response. - If
fields
attribute is specified with empty object, or bothinclude
andexclude
set to null or an empty array returned attributes for each item will be as ifinclude
was set to default set of["id", "type", "geometry", "bbox", "links", "assets", "properties.datetime"]
. - If only
include
is specified, the attributes ininclude
will be merged with the default set above. - If only
exclude
is specified, the attributes inexclude
will be removed from the default set above. - If both
include
andexclude
are specified, the rule is that attribute must be included and not excluded to be returned in response.
Distinct
Sometimes we don't want to search for the actual product metadata but want some general information about products inside our search parameters. For example which aquisition dates are available for Sentinel 1 GRD imagery inside specified bbox
and time interval. distinct
attribute inside search request makes this possible.
Syntax for distinct
attribute is:
{"distinct": "<property_name>"}
As with query
attribute, distinct
is also collection limited to some specific properties. Information describing these properties can be found inside each collection's documentation (ex. Sentinel 1 GRD).