Skip to main content

Catalog API

The Catalog API implements the STAC Specification, describing geospatial information about the data collections you have access to.

API Reference​

API Reference for Catalog is available as an OpenAPI description.

Simple search request for Sentinel-1 GRD with a bounding box (the coordinate reference system of the values is WGS84 longitude/latitude), available on 10th December 2019.

data = {
    "bbox": [13, 45, 14, 46],
    "datetime": "2019-12-10T00:00:00Z/2019-12-10T23:59:59Z",
    "collections": ["sentinel-1-grd"],
    "limit": 5,
}

url = "https://services.sentinel-hub.com/api/v1/catalog/1.0.0/search"
response = requests.post(url, json=data)

Authentication​

For information about how to authenticate with the Catalog API, see the Authentication chapter.

Deployments​

DeploymentAPI end-pointRegion
AWS EU (Frankfurt)https://services.sentinel-hub.com/api/v1/catalogeu-central-1
AWS US (Oregon)https://services-uswest2.sentinel-hub.com/api/v1/catalogus-west-2

Pagination​

Executing the request specified above returns search context fields at the end of the response, for example:

{
  "context": {
    "next": 5,
    "limit": 5,
    "returned": 5
  }
}

The presence of the next attribute indicates there is more data available for this query, but the server chose to only return 5 results, because the limit specified was 5. If limit is not specified, default value is 10. To query the next page of items, the request needs to include the next attribute with its value in the query, for example:

data = {
    "bbox": [13, 45, 14, 46],
    "datetime": "2019-12-10T00:00:00Z/2019-12-10T23:59:59Z",
    "collections": ["sentinel-1-grd"],
    "limit": 5,
    "next": 5,
}

url = "https://services.sentinel-hub.com/api/v1/catalog/1.0.0/search"
response = requests.post(url, json=data)

The response includes the next page of items; in this case there is no next token in context, meaning no more items exist for this query.

Extensions​

Filter​

The search endpoint by default only accepts the parameters described in OpenAPI. The Filter extension enables users to specify an additional parameter to filter on, while searching through data.

The syntax for filter is CQL2:

{
  "filter": {
    "op": "<operator>",
    "args": [
      {
        "property": "<property_name>"
      },
      "<value>"
    ]
  },
  "filter-lang": "cql2-json"
}

It is also possible to use simple cql2-text:

{
  "filter": "eo:cloud_cover > 90"
}

The available operators are eq, neq, lt, lte, gt, gte and between. Only and is currently supported as a logical operator. Be careful - different collections have different properties for the query filter available. The information describing this is available inside the documentation for each specific collection (for exanple, Sentinel-1 GRD).

Fields​

By default, the search endpoint returns all the available attributes of each item. The fields extension provides a way for 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": ["<property_name_1>", "<property_name_2>"],
    "exclude": ["<property_name_3>", "<property_name_4>", "<property_name_5>"]
  }
}

Include/Exclude behaviour​

  • When the fields attribute is not specified in the request, all the available attributes will be included in the response.
  • If the fields attribute is specified with an empty object, or both include and exclude are set to null or an empty array is returned, the attributes for each item will be as if include was set to a 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 an attribute must be included in and not excluded from the response.

Distinct​

Sometimes we do not want to search for product metadata, but we want some general information about the product. For example, which acquisition dates are available for Sentinel-1 inside the specified bbox and time interval. The distinct attribute inside a search request makes this possible.

Syntax for distinct attribute is:

{
  "distinct": "<property_name>"
}

As with the filter attribute, distinct is also a collection limited to some specific properties. Information describing these properties can be found inside each collection's documentation (for example, Sentinel-1 GRD).

Last updated on