Skip to main content

Single dataset search

Search API for a single dataset where the value of the dataset parameter is specified in the URL.

Get the list of scenes that cover users fields

HTTP Request

POST 'https://api-connect.eos.com/api/lms/search/v2/<dataset_id>?api_key=<your_api_key>' \
--data-raw '{
"search": {
"date": {"from":"date","to":"date"},
"cloudCoverage":{"from": number,"to": number},
"shape": { "type": "Polygon",
"coordinates": [
[ [lon,lat],
[lon,lat],
.........,
[lon,lat],
[lon,lat],
]
]
}
},
"sort":{"date":"desc"},
"fields": ["sceneID","cloudCoverage"],
"limit": number,
"page": number
}

Request Parameters

Request Path ParameterDescription
api_key(Required) Apikey retrieved from developer portal
dataset_id(Required) One of the available dataset_id
Request Body ParameterDescription
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.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/.
search.shapeRelation(optional - only used with shape) - relation between requested shape geometry and matching scenes.
Valid values are:
INTERSECTS (default) - the geometry in the request and the scene geometry intersect ,
CONTAINS - the scene geometry CONTAINS geometry in the request (100% coverage of the request geometry by the scene geometry),
DISJOINT - the geometry in the request and the scene geometry do not intersect,
WITHIN - the scene geometry inside the request geometry (100% coverage of the scene geometry by the request geometry).
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
intersection_validation(optional) If true, enables additional validation for relation between shape and geometry of the scenes (false by default).
Relation is determined by shapeRelation filter value.
Note: Pagination and found scene counter are not fully supported in conjunction with this parameter.
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. Example: [‘sceneId’, ‘cloudCover’]

HTTP Response

{
"results": [
{
"tms": "link",
"sceneID": "scene’s identifier",
"cloudCoverage": number,
"view_id": "view’s identifier"
},
{....................},
{
"tms": "link",
"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;
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;

Examples

Search scenes for Sentinel2

curl --location --request POST 'https://api-connect.eos.com/api/lms/search/v2/sentinel2' \
--header 'Content-Type: text/plain' \
--header 'x-api-key: <your_api_key>' \
--data '{
"fields": [
"sunElevation", "cloudCoverage", "sceneID", "date",
"productID", "sensor", "dataCoveragePercentage"
],
"limit": 2,
"page": 1,
"search": {
"date": {"from": "2023-06-01","to": "2023-07-31"},
"cloudCoverage": {"from": 0,"to": 90},
"shape": {
"type": "Polygon",
"coordinates": [
[
[-86.86718,41.317464],
[-86.86718,41.331596],
[-86.862631,41.331596],
[-86.862631,41.317464],
[-86.86718,41.317464]
]
]
}
},
"sort":{"date":"desc"}
}'

curl --location --request POST 'https://api-connect.eos.com/api/lms/search/v2/sentinel2?api_key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"fields": ["sceneID","cloudCoverage"],
"limit": 2,
"page": 1,
"search": {
"date": {"from": "2020-01-01","to": "2020-07-31"},
"cloudCoverage": {"from": 0,"to": 60},
"shape": {
"type": "Polygon",
"coordinates": [
[
[-122.074413,39.512815],
[-122.067783,39.512749],
[-122.067761,39.51111],
[-122.07437,39.51111],
[-122.074413,39.512815]
]
]
}
},
"sort":{"date":"desc"}
}

Response to request for search scene for Sentinel2
{
"meta": {
"page": 1,
"found": 17,
"name": "satellite-meta-service",
"limit": 2
},
"results": [
{
"sunElevation": 62.7193936329362,
"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
},
{
"sunElevation": 64.2465407798637,
"view_id": "S2/16/T/EL/2023/7/29/0",
"dataCoveragePercentage": 59.01,
"sceneID": "S2A_tile_20230729_16TEL_0",
"date": "2023-07-29",
"cloudCoverage": 75.7
}
]
}

Search scenes for Landsat9

curl --location --request POST 'https://api-connect.eos.com/api/lms/search/v2/landsat9' \
--header 'Content-Type: text/plain' \
--header 'x-api-key: <your_api_key>' \
--data '{
"fields": [
"sunElevation", "cloudCoverage", "sceneID", "date","sensor", "dataCoveragePercentage"
],
"limit": 2,
"page": 1,
"search": {
"date": {"from": "2023-06-01","to": "2023-07-31"},
"cloudCoverage": {"from": 0,"to": 90},
"shape": {
"type": "Polygon",
"coordinates": [
[
[-86.86718,41.317464],
[-86.86718,41.331596],
[-86.862631,41.331596],
[-86.862631,41.317464],
[-86.86718,41.317464]
]
]
}
},
"sort":{"date":"desc"}
}'
Response to request for search scene for Landsat9
{
"meta": {
"page": 1,
"found": 3,
"name": "satellite-meta-service",
"limit": 2
},
"results": [
{
"sunElevation": 60.29310356,
"view_id": "L9/LC09_L1TP_022031_20230731_20230801_02_T1",
"sceneID": "LC09_L1TP_022031_20230731_20230801_02_T1",
"sensor": "OLI_TIRS",
"date": "2023-07-31",
"cloudCoverage": 11.51,
"awsPath": "collection02/level-1/standard/oli-tirs/2023/022/031/LC09_L1TP_022031_20230731_20230801_02_T1/"
},
{
"sunElevation": 63.02642204,
"view_id": "L9/LC09_L1TP_022031_20230715_20230715_02_T1",
"sceneID": "LC09_L1TP_022031_20230715_20230715_02_T1",
"sensor": "OLI_TIRS",
"date": "2023-07-15",
"cloudCoverage": 37.73,
"awsPath": "collection02/level-1/standard/oli-tirs/2023/022/031/LC09_L1TP_022031_20230715_20230715_02_T1/"
}
]
}

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