Catalog API Examples

To request data using any of the request below, you will need to replace the string <your access token> with your Sentinel Hub access token. Sentinel Hub access token will look something like this:

ayJhbGciOiJSUzI1NiJ9.ayJzdWIiOiI0MmYwODZjCy1kMzI3LTRlOTMtYWMxNS00ODAwOGFiZjI0YjIiLCJhdWQiOiJlY2I1MGM1Zi1i
MWM1LTQ3ZTgtYWE4NC0zZTU4NzJlM2I2MTEiLCJqdGkiOiI5MzYxMWE4ODEyNTM4Y2M0MmU0NDJjYjUyMTY0YmJlNyIsImV4cCI6MTU1N
TQyMzk3MiwibmFtZSI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLCJlbWFpbCI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLC
JzaWQiOiIzZjVjZDVkNS04MjRiLTQ3ZjYtODgwNy0wNDMyNWY4ODQxZmQifQ.U7FPOy_2jlEOFxXSjyN5KEdBROna3-Dyec0feShIbUOY
1p9lEXdNaMmR5euiINi2RXDayX9Kr47CuSTsvq1zHFvZs1YgkFr1iH6kDuX-t_-wfWpqu5oPjoPVKZ4Rj0Ms_dxAUTQFTXR0rlbLuO-KS
gnaeLVb5iiv_qY3Ctq2XKdIRcFRQLFziFcP4yZJl-NZMlwzsiiwjakcpYpI5jSYAdU2hpZLHRzceseeZt5YfZOe5Px1kZXro9Nd0L2GPC
-qzOXw_V1saMGFa2ov8qV6Dvk92iv2SDDdGhOdII_JOf8XkK4E3g2z0EEFdWhG9F4Iky4ukNsqBPgE8LRb31s0hg

and can be obtained as described in the Authentication chapter.

A Postman collection with examples can be downloaded here.

Catalog API Entry page

Catalog API Entry page with link to other catalog API endpoints and available collections.

curl -X GET 'https://services.sentinel-hub.com/api/v1/catalog/'

List collections

List all available collections. The list will include deployment specific collections and collections available to users through BYOC, Batch or Third Party Data Import functionalities.

curl -X GET 'https://services.sentinel-hub.com/api/v1/catalog/collections' \
  --header 'Authorization: Bearer <your access token>'

Sentinel 2 L1C collection

List single collection, in this case Sentinel 2 L1C collection.

curl -X GET 'https://services.sentinel-hub.com/api/v1/catalog/collections/sentinel-2-l1c/' \
--header 'Authorization: Bearer <your access token>'

Simple version of search available via GET request is also available. The only query parameters that can be specified in this simpler version are: bbox, datetime, collections, limit and next.

curl -X GET 'services.sentinel-hub.com/api/v1/catalog/search?bbox=13,45,14,46&limit=5&collections=sentinel-1-grd&datetime=2019-12-10T00:00:00Z/2019-12-11T00:00:00Z' \
--header 'Authorization: Bearer <your access token>'

Simple POST search

The same parameters can also be specified a POST request, query parameters need to be specified as json formatted body and sent to server 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
  }'

Simple POST search with pagination

next token can be specified in the request to get back the next page of results.

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
}'

Search with GeoJSON

Instead of bbox it is possible to add intersects attribute, which can be any type of GeoJSON object (Point, LineString, Polygon, MultiPoint, MultiPolygon).

curl -X POST 'services.sentinel-hub.com/api/v1/catalog/search' \
--header 'Authorization: Bearer <your access token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datetime": "2019-12-10T00:00:00Z/2019-12-11T00:00:00Z",
    "collections": ["sentinel-1-grd"],
    "limit": 5,
    "intersects": {
        "type": "Point",
        "coordinates": [
            13,
            45
        ]
    }
}'

Search with Query

query object can be used to instruct server to only return a specific subset of data.

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-11T00:00:00Z",
    "collections": ["sentinel-1-grd"],
    "limit": 5,
    "query": {
        "sat:orbit_state": {
            "eq": "ASCENDING"
        }
    }
}'

Search with Fields: No fields

Default outputs from the server can be quite verbose for some of the collections. By default all available item properties are included in the response.

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-11T00:00:00Z",
    "collections": ["sentinel-2-l1c"],
    "limit": 1
}'

Search with Fields: Empty fields

fields attribute can be specific to return less information. When fields object is empty only a default set of properties is included: id, type, geometry, bbox, links, assets.

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-11T00:00:00Z",
    "collections": ["sentinel-2-l1c"],
    "limit": 1,
    "fields": {}
}'

Search with Fields: Include

By specifying additional attributes in the include list, those attributes are added to the output along with the default ones.

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-11T00:00:00Z",
    "collections": ["sentinel-2-l1c"],
    "limit": 1,
    "fields": {"include": ["properties.eo:gsd"]}
}'

Search with Fields: Exclude

exlude list can be used to exclude even the default ones from the output.

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-11T00:00:00Z",
    "collections": ["sentinel-2-l1c"],
    "limit": 1,
    "fields": {"exclude": ["properties.datetime"]}
}'

Search with distinct

Using distinct it is possible to get some overview of the data available inside the specified query. For example specifying date as an option will return a list of dates where data is available.

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-01T00:00:00Z/2020-01-01T00:00:00Z",
    "collections": ["sentinel-1-grd"],
    "limit": 100,
    "distinct": "date"
}'

Or see different Sentinel 1 instrument modes used.

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-01T00:00:00Z/2020-01-01T00:00:00Z",
    "collections": ["sentinel-1-grd"],
    "limit": 100,
    "distinct": "sar:instrument_mode"
}'