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 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", "properties.datetime"].
• If only include is specified, the attributes in include will be merged with the default set above.
• If only exclude is specified, the attributes in 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 collection limited to some specific properties. Information describing these properties can be found inside each collection's documentation (ex. Sentinel 1 GRD).