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