Skip to main content

Catalog API Examples

To request data using any of the requests below, you will need to replace the string <your access token> with your access token. 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.

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/1.0.0/

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/1.0.0/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/1.0.0/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 -G https://services.sentinel-hub.com/api/v1/catalog/1.0.0/search \
  --header 'Authorization: Bearer <your access token>' \
  --data 'bbox=13,45,14,46' \
  --data 'datetime=2019-12-10T00:00:00Z/2019-12-11T00:00:00Z' \
  --data 'collections=sentinel-1-grd' \
  --data 'limit=5'

Simple POST Search​

The same parameters can also be specified in a POST request. Query parameters need to be specified as a json formatted body and sent to server. For example:

curl -X POST https://services.sentinel-hub.com/api/v1/catalog/1.0.0/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​

The next token can be specified in the request to retrieve the next page of results.

curl -X POST https://services.sentinel-hub.com/api/v1/catalog/1.0.0/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
  }'

Search with GeoJSON​

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

curl -X POST https://services.sentinel-hub.com/api/v1/catalog/1.0.0/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 Filter​

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

curl -X POST https://services.sentinel-hub.com/api/v1/catalog/1.0.0/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,
    "filter": "sat:orbit_state='\''ascending'\''"
  }'

Get Filter Parameters for Collection​

List all available filter parameters represented as JSON Schema.

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

Search with Fields: No Fields​

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

curl -X POST https://services.sentinel-hub.com/api/v1/catalog/1.0.0/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​

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

curl -X POST https://services.sentinel-hub.com/api/v1/catalog/1.0.0/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 https://services.sentinel-hub.com/api/v1/catalog/1.0.0/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.gsd"]}
  }'

Search with Fields: Exclude​

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

curl -X POST https://services.sentinel-hub.com/api/v1/catalog/1.0.0/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 makes it 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 https://services.sentinel-hub.com/api/v1/catalog/1.0.0/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 https://services.sentinel-hub.com/api/v1/catalog/1.0.0/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/Zarr Collections​

You can search for features on your own BYOC or Zarr 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 the collections parameter (for example, byoc-<your-collection-id> for byoc or zarr-<your-collection-id> for zarr). 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/1.0.0/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": ["byoc-<byoc-collection-id>"],
    "limit": 5
  }'

Or using GET simple search endpoint:

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