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.ayJzdWIiOiI0MmYwODZjCy1kMzI3LTRlOTMtYWMxNS00ODAwOGFiZjI0YjIiLCJhdWQiOiJlY2I1MGM1Zi1iMWM1LTQ3ZTgtYWE4NC0zZTU4NzJlM2I2MTEiLCJqdGkiOiI5MzYxMWE4ODEyNTM4Y2M0MmU0NDJjYjUyMTY0YmJlNyIsImV4cCI6MTU1NTQyMzk3MiwibmFtZSI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLCJlbWFpbCI6ImFuamEudnJlY2tvQHNpbmVyZ2lzZS5jb20iLCJzaWQiOiIzZjVjZDVkNS04MjRiLTQ3ZjYtODgwNy0wNDMyNWY4ODQxZmQifQ.U7FPOy_2jlEOFxXSjyN5KEdBROna3-Dyec0feShIbUOY1p9lEXdNaMmR5euiINi2RXDayX9Kr47CuSTsvq1zHFvZs1YgkFr1iH6kDuX-t_-wfWpqu5oPjoPVKZ4Rj0Ms_dxAUTQFTXR0rlbLuO-KSgnaeLVb5iiv_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 GET search
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"}'