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 '{
"intersection_validation": true,
"search": {
"date": {"from":"date","to":"date"},
"cloudCoverage":{"from": number,"to": number},
"shapeRelation": "CONTAINS",
"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 Parameter | Description |
|---|---|
| api_key | (Required) Apikey retrieved from developer portal |
| dataset_id | (Required) One of the available dataset_id |
| Request Body Parameter | Description |
|---|---|
| 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​
| Parameter | Description |
|---|---|
| tms | The link to tile map; |
| sceneID | The scene’s identifier; |
| cloudCoverage | Value of Cloud Coverage for the scene; |
| view_id | The view’s identifier; |
| found | Quantity of scene found; |
| page | Quantity of page with scenes; |
| limit | Quantity of scenes returned; |
| and other parameters | Other 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": 500,
"page": 1,
"search": {
"intersection_validation": true,
"date": {"from": "2023-06-01","to": "2023-07-31"},
"cloudCoverage": {"from": 0,"to": 90},
"shapeRelation": "CONTAINS",
"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 Sentinel2​
{
"meta": {
"found": 17,
"name": "satellite-meta-service",
"page": 1,
"limit": 2
},
"results": [
{
"date": "2023-07-31",
"sunElevation": 62.7193936329362,
"cloudCoverage": 2.0,
"dataGeometry": {
"coordinates": [
[
[
-87.00022782817362,
41.55183566226867
],
[
-87.00022444079165,
40.56275892201299
],
[
-85.70337428842777,
40.555482279926174
],
[
-85.68381174363218,
41.544302667202295
],
[
-87.00022782817362,
41.55183566226867
]
]
],
"type": "Polygon",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG:8.9:4326"
}
}
},
"sceneID": "S2B_tile_20230731_16TEL_0",
"dataCoveragePercentage": 100.0,
"tms": "https://render.eosda.com/S2/16/T/EL/2023/7/31/0/{band}/{z}/{x}/{y}",
"view_id": "S2/16/T/EL/2023/7/31/0"
},
{
"date": "2023-07-29",
"sunElevation": 64.2465407798637,
"cloudCoverage": 75.7,
"dataGeometry": {
"coordinates": [
[
[
-87.00022782817362,
41.55183566226867
],
[
-87.00022444380076,
40.5636598179917
],
[
-86.40715370319707,
40.56231853513746
],
[
-86.04684004963566,
41.54788519803006
],
[
-87.00022782817362,
41.55183566226867
]
]
],
"type": "Polygon",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG:8.9:4326"
}
}
},
"sceneID": "S2A_tile_20230729_16TEL_0",
"dataCoveragePercentage": 59.01,
"tms": "https://render.eosda.com/S2/16/T/EL/2023/7/29/0/{band}/{z}/{x}/{y}",
"view_id": "S2/16/T/EL/2023/7/29/0"
}
]
}
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": 500,
"page": 1,
"intersection_validation": true,
"search": {
"date": {"from": "2023-06-01","to": "2023-07-31"},
"cloudCoverage": {"from": 0,"to": 90},
"shapeRelation": "CONTAINS",
"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": {
"found": 3,
"name": "satellite-meta-service",
"page": 1,
"limit": 2
},
"results": [
{
"date": "2023-07-31",
"sunElevation": 60.29310356,
"awsPath": "collection02/level-1/standard/oli-tirs/2023/022/031/LC09_L1TP_022031_20230731_20230801_02_T1/",
"cloudCoverage": 11.51,
"sceneID": "LC09_L1TP_022031_20230731_20230801_02_T1",
"dataGeometry": {
"coordinates": [
[
[
-87.60622652147855,
42.80946719025564
],
[
-88.14245077923233,
41.09475821555301
],
[
-85.9859806995821,
40.693563919146705
],
[
-85.39160776849965,
42.405878260618216
],
[
-87.60622652147855,
42.80946719025564
]
]
],
"type": "Polygon"
},
"sensor": "OLI_TIRS",
"tms": "https://render.eosda.com/L9/LC09_L1TP_022031_20230731_20230801_02_T1/{band}/{z}/{x}/{y}",
"view_id": "L9/LC09_L1TP_022031_20230731_20230801_02_T1",
"thumbnail": "https://usgs-landsat.eos.com/collection02/level-1/standard/oli-tirs/2023/022/031/LC09_L1TP_022031_20230731_20230801_02_T1/LC09_L1TP_022031_20230731_20230801_02_T1_thumb_small.jpeg"
},
{
"date": "2023-07-15",
"sunElevation": 63.02642204,
"awsPath": "collection02/level-1/standard/oli-tirs/2023/022/031/LC09_L1TP_022031_20230715_20230715_02_T1/",
"cloudCoverage": 37.73,
"sceneID": "LC09_L1TP_022031_20230715_20230715_02_T1",
"dataGeometry": {
"coordinates": [
[
[
-87.61870137725101,
42.80940046632809
],
[
-88.15495108205951,
41.094633579197996
],
[
-85.99841036071045,
40.69340217691492
],
[
-85.40364750135215,
42.40550624442422
],
[
-87.61870137725101,
42.80940046632809
]
]
],
"type": "Polygon"
},
"sensor": "OLI_TIRS",
"tms": "https://render.eosda.com/L9/LC09_L1TP_022031_20230715_20230715_02_T1/{band}/{z}/{x}/{y}",
"view_id": "L9/LC09_L1TP_022031_20230715_20230715_02_T1",
"thumbnail": "https://usgs-landsat.eos.com/collection02/level-1/standard/oli-tirs/2023/022/031/LC09_L1TP_022031_20230715_20230715_02_T1/LC09_L1TP_022031_20230715_20230715_02_T1_thumb_small.jpeg"
}
]
}
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>'
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>'
