Catalog API

Sentinel Hub Catalog is API implementing the STAC Specification to describe geospatial information about different data used inside Sentinel Hub.

API Reference

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 Catalog API works completely the same as authentication for 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
    }
}

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 it's 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 datasets have different properties available that can be used as propery inside query filter. Information describing this is available inside documentation for each specific dataset (ex. Sentinel 1 GRD).

Fields

By default 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 both include and exclude set to null or an empty array returned attributes for each item will be as if include was set to default set of ["id", "type", "geometry", "bbox", "links", "assets"].
• If only include is specified, the attributes in the include will be merged with the default set above.
• If only exclude is specified, the attributes in the exclude will be removed from the default set above.
• If both include and exclude 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 dataset limited to some specific properties. Information describing these properties can be found inside each dataset's documentation (ex. Sentinel 1 GRD).