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

Search on BYOC/BATCH collections

You can search for features on your own BYOC or Batch collections. The functionality described above regarding GET and POST search is the same. The only difference is that you have to specify the collection id with the appropriate prefix on collections parameter (e.g: byoc-<your-collection-id> for byoc or batch-<your-collection-id> for batch). Remember that you will have to use the appropriate deployment endpoint depending on where your collection is hosted.

curl -X POST https://services.sentinel-hub.com/api/v1/catalog/search \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer <your access token>' \
 -d '{
  "collections": [
    "byoc-<byoc-collection-id>"
  ],
  "datetime": "2021-01-20T00:00:00Z/2021-10-20T23:59:59Z",
  "bbox": [
    12.44693,
    41.870072,
    12.541001,
    41.917096
  ],
  "limit": 10
}'

Or using GET simple search endpoint:

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