Skip to main content

Multi-dataset search

Search API for multiple datasets. Datasets are listed under required search.satellites field instead of URL.

Another significant difference from the Simple search request is that search filter is ignored for the dataset if the field is not present in the mapping for said dataset.

Get the list of scenes that cover users fields

HTTP Request

POST 'https://api-connect.eos.com/api/lms/search/v2?api_key=<your_api_key>' \
--data-raw '{
"fields": [
"sunElevation", "cloudCoverage", "sceneID", "date",
"productID", "sensor", "dataCoveragePercentage"
],
"limit": number,
"page": number,
"search": {
"satellites": ["satellite name1","...", "satellite name N"],
"date": {"from": "2019-08-01", "to": "2020-06-01"},
"cloudCoverage": {"from": number,"to": number},
"sunElevation": {"from": number,"to": number},
"shape": {
"type": "Polygon",
"coordinates": [
[ [lon,lat],
[lon,lat],
.........,
[lon,lat],
[lon,lat],
]
]
}
}
}

Request Parameters

Request Path ParameterDescription
api_key(Required) Apikey retrieved from developer portal
Request Body ParameterDescription
satellites(required) Use for this parameter one or more values from the list of sensor names (it's the value of dataset_id from Supported Datasets
search(required) Request parameters. Search request can be a combination of filters for any of dataset’s fields except for tms and view_id.
search.date(required) Range of the dates. There are different filters to apply:
1. match documents who’s field’s value is within the query’s range: {‘fieldName’: {‘from’: ‘val1’, ‘to’: ‘val2’}};
2. match documents who’s field’s value is one of the query’s values: {‘fieldName’: [‘v0’, ‘v1’, ‘v2’]};
3. match documents who’s field’s value matches the query exactly: {‘fieldName’: ‘value’}.

Examples:
1. find all scenes acquired in 2016: ‘date’: {‘from’: ‘2016-01-01’, ‘to’: ‘2016-12-31’};
2. find scenes acquired either on 1 August 2016, 1 September 2016, 1 October 2016: ‘date’: [‘2016-08-01’, ‘2016-09-01’, ‘2016-10-01’];
3. find scenes acquired on 1 August 2016: ‘date’: ‘2016-08-01’
Please note that for optimal service stability, it is recommended to search up to 365 days (1 year) as date range
search.cloudCoverage(optional) Range of cloud cover percentages by scenes.
search.sunElevation(optional) Range of sun elevations by scenes.
search.shape(required) A GeoJSON representation of a geometry describing the AOI. Supported geometry types: "Polygon" and "Point"
*Please note: : when you add coordinates in the first place - longitude and in the second - latitude. You can use these tools to check if the coordinates are valid https://geojson.io/, https://geojsonlint.com/****.
sort(optional) Sorting to perform.
Can either be in the form fieldName:asc or fieldName:desc.
Example: cloudCover: asc (sort results such that the least cloudy scenes come first).
Default: date: desc (the newest scenes come first)
page(optional) Number of page, used for pagination. Default: 1
limit(optional) Number of results per page. Default: 500
fields(optional) An array of the selective stored fields of the document to return for each hit, comma-delimited. More details about the available filter parameters

Not specifying any value will cause all available fields to return.

HTTP Response

{
"results": [
{
"tms": "link",
"satellite": "satellite name",
"sceneID": "scene’s identifier",
"cloudCoverage": number,
"view_id": "view’s identifier"
},
{....................},
{
"tms": "link",
"satellite": "satellite name",
"sceneID": "scene’s identifier",
"cloudCoverage": number,
"view_id": "view’s identifier"
} ],
"meta": {
"found": number,
"name": "satellite-meta-service",
"page": number,
"limit": number
}
}

Response parameters

ParameterDescription
tmsThe link to tile map;
satelliteThe satellite name;
sceneIDThe scene’s identifier;
cloudCoverageValue of Cloud Coverage for the scene;
view_idThe view’s identifier;
foundQuantity of scene found;
pageQuantity of page with scenes;
limitQuantity of scenes returned;
and other parametersOther parameters are available if you change request conditions;

Example

Search scene for Sentinel2l2a and Landsat8, Landsat9

curl --location --request POST 'https://api-connect.eos.com/api/lms/search/v2' \
--header 'Content-Type: text/plain' \
--header 'x-api-key: <your_api_key>' \
--data '{
"fields": [
"cloudCoverage", "sceneID", "date", "productID","dataCoveragePercentage"
],
"onAmazon": true,
"page": 1,
"search": {
"satellites": ["landsat9","landsat8","sentinel2l2a"],
"date": {"from": "2023-06-01","to": "2023-07-31"},
"cloudCoverage": {"from": 0,"to": 50},
"shape": {
"type": "Polygon",
"coordinates": [
[
[-86.86718,41.317464],
[-86.86718,41.331596],
[-86.862631,41.331596],
[-86.862631,41.317464],
[-86.86718,41.317464]
]
]
}
}
}'

Response to request for search scene for Sentinel2l2a and Landsat8, Landsat9

{
"meta": {
"page": 1,
"found": 17,
"name": "satellite-meta-service",
"limit": 10
},
"results": [
{
"view_id": "S2/16/T/EL/2023/7/31/0",
"dataCoveragePercentage": 100.0,
"sceneID": "S2B_tile_20230731_16TEL_0",
"date": "2023-07-31",
"cloudCoverage": 2.0,
"awsPath": "tiles/16/T/EL/2023/7/31/0",
"satellite": "sentinel2"
},
{
"view_id": "L9/LC09_L1TP_022031_20230731_20230801_02_T1",
"sceneID": "LC09_L1TP_022031_20230731_20230801_02_T1",
"date": "2023-07-31",
"cloudCoverage": 11.51,
"awsPath": "collection02/level-1/standard/oli-tirs/2023/022/031/LC09_L1TP_022031_20230731_20230801_02_T1/",
"satellite": "landsat9"
},
{
"view_id": "L8/LC08_L1TP_022031_20230723_20230803_02_T1",
"sceneID": "LC08_L1TP_022031_20230723_20230803_02_T1",
"date": "2023-07-23",
"cloudCoverage": 19.56,
"awsPath": "collection02/level-1/standard/oli-tirs/2023/022/031/LC08_L1TP_022031_20230723_20230803_02_T1/",
"satellite": "landsat8c2l1"
},
...
]
}

Indices-statistics example

Render example

After that you can render scenes you've get before in the Search API, with Render API, just use view_id parameter, band name and z, x, y, for example:

Natural view:

curl --location --request GET 'https://api-connect.eos.com/api/render/S2/36/U/XU/2016/5/2/0/B04,B03,B02/10/611/354' \
--header 'x-api-key: <your_api_key>'

Render natural color example

NDVI:

curl --location --request GET 'https://api-connect.eos.com/api/render/S2/36/U/XU/2016/5/2/0/NDVI/10/611/354' \
--header 'x-api-key: <your_api_key>'

Render natural color example