Example snippets
Examples of using EOSDA API Connect demonstrating how to retrieve images, weather data, or analytics related to vegetation indices.
I. Get raster image with cloudmask (Sentinel2)
For to get raster image you need to find a scene and get a view_id and make a cropper_ref from your geometry
Step 1: find a scene and get a view_id:
POST https://api-connect.eos.com/api/lms/search/v2/sentinel2?api_key={{api_key}}
{
"fields": [
"sceneID",
"cloudCoverage"
],
"limit": 2, ← select limit for results
"page": 1, ← select results page quantity
"search": {
"date": { ← select date range for search scene
"from": "2018-04-01",
"to": "2018-08-01"
},
"cloudCoverage": { ← select cloud coverage range
"from": 0,
"to": 80
},
"shape": { ← your geometry in geoJSON forman
"type": "Polygon",
"coordinates": [
[
[
32.09501266479492,
49.91389971409139
],
[
32.08308219909668,
49.90549799617724
],
[
32.08286762237548,
49.90395015166309
],
[
32.08385467529296,
49.90295508253476
],
[
32.08548545837402,
49.902125842582244
],
[
32.08724498748779,
49.901268946323746
],
[
32.089219093322754,
49.900964882702596
],
[
32.09286689758301,
49.9039225111311
],
[
32.09179401397705,
49.901407156427155
],
[
32.0965576171875,
49.905636194165126
],
[
32.104926109313965,
49.912213960435274
],
[
32.10162162780762,
49.91439713833688
],
[
32.09501266479492,
49.91389971409139
]
]
]
}
},
"sort": {
"date": "desc" ← select sorting
}
}
Response:
{
"results": [
{
"tms": "https://api-connect.eos.com/api/render/S2/36/U/VA/2018/8/1/0/{band}/{z}/{x}/{y}",
"cloudCoverage": 29.93,
"view_id": "S2/36/U/VA/2018/8/1/0",
"sceneID": "S2B_tile_20180801_36UVA_0"
},
{
"tms": "https://api-connect.eos.com/api/render/S2/36/U/VA/2018/7/29/0/{band}/{z}/{x}/{y}",
"cloudCoverage": 74.22,
"view_id": "S2/36/U/VA/2018/7/29/0", ← choose one of found scene’s view_id
"sceneID": "S2B_tile_20180729_36UVA_0"
}
],
"meta": {
"limit": 2,
"found": 41,
"page": 1,
"name": "satellite-meta-service"
}
}
Step 2: get a cropper_ref for your geometry
cropper_ref that is kind of an ID of your geometry, you should put coordinates in geoJSON format
POST https://api-connect.eos.com/api/render/cropper/?api_key={{api_key}}
{
"type": "Feature",
"properties": {},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
32.09501266479492,
49.91389971409139
],
[
32.08308219909668,
49.90549799617724
],
[
32.08286762237548,
49.90395015166309
],
[
32.08385467529296,
49.90295508253476
],
[
32.08548545837402,
49.902125842582244
],
[
32.08724498748779,
49.901268946323746
],
[
32.089219093322754,
49.900964882702596
],
[
32.09286689758301,
49.9039225111311
],
[
32.09179401397705,
49.901407156427155
],
[
32.0965576171875,
49.905636194165126
],
[
32.104926109313965,
49.912213960435274
],
[
32.10162162780762,
49.91439713833688
],
[
32.09501266479492,
49.91389971409139
]
]
]
}
}
Response:
{
"cropper_ref": "c1ed395b639a3b86f64748509da9c4e6"
}
Step 3: create colormap
You can create colormap for images based on your personal color scheme for every index value
POST https://api-connect.eos.com/api/render/colormap/?api_key={{api_key}}
{
"type": "continuous",
"colors": [
[
-0.3,
"#d7191c"
],
[
0.3,
"#fd3908"
],
[
0.6,
"#ff2b14"
],
[
0.62,
"#d96309"
],
[
0.64,
"#ef911d"
],
[
0.67,
"#ffa73a"
],
[
0.69,
"#ffc619"
],
[
0.71,
"#ffd323"
],
[
0.73,
"#ffe745"
],
[
0.76,
"#bed263"
],
[
0.78,
"#2bcf16"
],
[
0.8,
"#0aba24"
],
[
0.82,
"#159419"
],
[
0.85,
"#0e7e0a"
],
[
0.87,
"#0f5f0f"
],
[
1,
"#08590e"
]
],
"thresholds_type": "absolute"
}
Response:
{"id": "bc8a3f5f7b27c301430ba32352544b24"}
Step 4: get raster image with cloudmask:
GET https://api-connect.eos.com/api/render/<view_id>/<index_general _formula>/<zoom>/<bbox>?<TILE_SIZE>&cropper_ref=<cropper_ref>CALIBRATE=1&COLORMAP=<colormap>&MIN_MAX=0,1&MASKING=CLOUD&MASK_COLOR=fefefe&api_key={{api_key}}
| Parameter name: | Parametr description | is required |
|---|---|---|
| view_id | from step #1 | required |
| index_general _formula | Formula or Alias for index that you need | required |
| zoom | zoom level for image, integer | required |
| TILE_SIZE | Set the tile size in px, for example: 250,250 | optional |
| bbox | boundary box - parameter to set boundaries of image, based on 4 points with geo anchor, in a format {x_min};{x_max};{reference}/{y_min};{y_max};{reference}. default value for {reference} is 4326 | required |
| MASKING | Should contain value CLOUD | required |
| cropper_ref | from step #2 | required |
| COLORMAP | colormap id from step #3 | required |
| MASK_COLOR | Any HEX-code color to paint a cloudmask, for example: FFFFFF | required |
| Calibrate | ToA Reflectance, boolean, 1 or 0 | optional |
| MIN_MAX | Set min or max accepted values for indices , from -1 to 1 | optional |
| api_key | your personal api key retrieved from user dashboard | required |
Filled request example:
GET https://api-connect.eos.com/api/render/S2/36/U/VA/2018/7/29/0/NDVI/10/32.08286762237548;32.104926109313965;4326/49.900964882702596; 49.91439713833688;4326?TILE_SIZE=400,400&cropper_ref=c1ed395b639a3b86f64748509da9c4e6&CALIBRATE=1&COLORMAP=2b0040e4100279573a41138c8a30c1f2&MIN_MAX=-1,1&MASKING=CLOUD&MASK_COLOR=cccccc&api_key={{api_key}}
II. Get indices statistics
Step 1: create a task
POST https://api-connect.eos.com/api/gdw/api?api_key={{api_key}}
{
"type": "mt_stats",
"params": {
"bm_type": [← set as array for multiple indices or as string for one
"NDVI",
"MSI",
"EVI",
"NDRE",
"SAVI",
"NDSI"
],
"date_start": "2020-12-01", ← set date range for search
"date_end": "2020-12-02",
"geometry": {
"coordinates": [
[
[
-1.531048,
5.578849
],
[
-1.530683,
5.575411
],
[
-1.521606,
5.576286
],
[
-1.522036,
5.579767
],
[
-1.531048,
5.578849
]
]
],
"type": "Polygon"
},
"reference": "ref_20210208-00-00",
"sensors": [
"sentinel2"
]
}
}
Response
{
"status": "created",
"task_id": "172cea25-5e43-4add-a326-a083915de015", ← take that id for the next step
"req_id": "55965b1b-b6db-47fd-a061-c7f24bf3e355",
}
"task_timeout": 345600
Notice TTL for task_id equal 48 hours Average time for completing task is around 7-10 sec
Step 2: get a task’s result
Take a task_id from previous step and put in into the URL
GET https://api-connect.eos.com/api/gdw/api/172cea25-5e43-4add-a326-a083915de015?api_key={{api_key}}
Response:
{
"errors": [],
"result": [
{
"scene_id": "S2B_tile_20201202_30NXM_0",
"view_id": "S2/30/N/XM/2020/12/2/0",
"date": "2020-12-02",
"cloud": 0.0,
"notes": [
"Failed to build EOS S2 cloud mask"
],
"indexes": {
"NDVI": {
"q1": 0.7423529773950577,
"q3": 0.7704117298126221,
"max": 0.8021047115325928,
"min": 0.4646700322628021,
"p10": 0.7014811336994171,
"p90": 0.779340922832489,
"std": 0.03900678669223714,
"median": 0.7589870691299438,
"average": 0.7480806991828332,
"variance": 0.001521529408053688
},
"MSI": {
"q1": 0.4958096221089363,
"q3": 0.5374680757522583,
"max": 0.7267305850982666,
"min": 0.4157608449459076,
"p10": 0.48286929726600647,
"p90": 0.5732181668281555,
"std": 0.037260449296009426,
"median": 0.5130902528762817,
"average": 0.5205532464538888,
"variance": 0.0013883410817404891
},
"EVI": {
"q1": 1.0533574223518372,
"q3": 1.1227656304836273,
"max": 1.2117210626602173,
"min": 0.5522392988204956,
"p10": 0.9688617885112762,
"p90": 1.1420115232467651,
"std": 0.07964261194640351,
"median": 1.0975471138954163,
"average": 1.0738818793634155,
"variance": 0.006342945637645415
},
"NDRE": {
"q1": -0.3974114805459976,
"q3": -0.36703331023454666,
"max": -0.33980581164360046,
"min": -0.5224010348320007,
"p10": -0.430104872584343,
"p90": -0.3561763495206833,
"std": 0.03065612339936341,
"median": -0.3807808756828308,
"average": -0.3869977667927742,
"variance": 0.0009397979018769968
},
"SAVI": {
"q1": 0.6202529966831207,
"q3": 0.6546447277069092,
"max": 0.6951528787612915,
"min": 0.3915958106517792,
"p10": 0.5834051966667175,
"p90": 0.6638062000274658,
"std": 0.03886944602387574,
"median": 0.641234427690506,
"average": 0.630471707530049,
"variance": 0.0015108338342029895
},
"NDSI": {
"q1": -0.4314165711402893,
"q3": -0.411478154361248,
"max": -0.11357814818620682,
"min": -0.47143495082855225,
"p10": -0.43910644948482513,
"p90": -0.39670228958129883,
"std": 0.029773477297031038,
"median": -0.42115436494350433,
"average": -0.4171930636220521,
"variance": 0.0008864599503568226
}
}
}
]
}
III. Download natural color image by users geometry
Step 1: find a scene
For example we’re take scene from section I, step 1: "view_id": "S2/36/U/VA/2018/7/29/0"
Step 2: create a task
POST https://api-connect.eos.com/api/gdw/api?api_key={{api_key}}
{
"type": "jpeg",
"params": {
"view_id": "S2/36/U/VA/2018/7/29/0",
"bm_type": "B01,B03,B04", ← details about band alias you can find in documentation
"geometry": {
"type": "Polygon",
"coordinates": [ ←should be the same as in scene search
[
[
32.09501266479492,
49.91389971409139
],
[
32.08308219909668,
49.90549799617724
],
[
32.08286762237548,
49.90395015166309
],
[
32.08385467529296,
49.90295508253476
],
[
32.08548545837402,
49.902125842582244
],
[
32.08724498748779,
49.901268946323746
],
[
32.089219093322754,
49.900964882702596
],
[
32.09286689758301,
49.9039225111311
],
[
32.09179401397705,
49.901407156427155
],
[
32.0965576171875,
49.905636194165126
],
[
32.104926109313965,
49.912213960435274
],
[
32.10162162780762,
49.91439713833688
],
[
32.09501266479492,
49.91389971409139
]
]
]
},
"px_size": 5,
"format": "png",
"reference": "RGB-ref_datetime"
}
}
{
"status": "created",
"task_id": "bdbfbb26-1c3a-40fa-827c-a9d97f3d93f2", ← take that id for the next step
"req_id": "4d300a96-3917-41af-a4d0-39a55b7361dc",
"task_timeout": 345600
}
Notice TTL for task_id equal 48 hours Average time for completing task is around 7-10 sec
Step 3: get a task’s result
GET https://api-connect.eos.com/api/gdw/api/bdbfbb26-1c3a-40fa-827c-a9d97f3d93f2?api_key={{api_key}}
IV. Get historical weather
POST https://api-connect.eos.com/api/cz/backend/forecast-history/?api_key={{api_key}}
{
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-1.531048,
5.578849
],
[
-1.530683,
5.575411
],
[
-1.521606,
5.576286
],
[
-1.522036,
5.579767
],
[
-1.531048,
5.578849
]
]
]
},
"start_date": "2020-12-11",
"end_date": "2020-12-14"
}
Response:
[
{
"temperature_min": "23",
"temperature_max": "30",
"vapour_pressure": "30",
"wind_speed": "6",
"rainfall": "5.1",
"show_depth": "0.0",
"hardening_index": "0.0",
"temp_critical": "0.0",
"date": "2020-12-11"
},
{
"temperature_min": "23",
"temperature_max": "30",
"vapour_pressure": "30",
"wind_speed": "6",
"rainfall": "4.4",
"show_depth": "0.0",
"hardening_index": "0.0",
"temp_critical": "0.0",
"date": "2020-12-12"
},
{
"temperature_min": "23",
"temperature_max": "30",
"vapour_pressure": "30",
"wind_speed": "6",
"rainfall": "19.5",
"show_depth": "0.0",
"hardening_index": "0.0",
"temp_critical": "0.0",
"date": "2020-12-13"
},
{
"temperature_min": "23",
"temperature_max": "30",
"vapour_pressure": "30",
"wind_speed": "6",
"rainfall": "13.6",
"show_depth": "0.0",
"hardening_index": "0.0",
"temp_critical": "0.0",
"date": "2020-12-14"
}
]
V. Get weather forecast
POST https://api-connect.eos.com/api/forecast/weather/forecast/?api_key={{api_key}}
{
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-1.531048,
5.578849
],
[
-1.530683,
5.575411
],
[
-1.521606,
5.576286
],
[
-1.522036,
5.579767
],
[
-1.531048,
5.578849
]
]
]
}
}
Response:
{
"Date": "2021-07-21",
"Temp_air_min": 22.6257568359375,
"Temp_air_max": 30.9792419433594,
"Temp_land_min": 23.7157531738281,
"Temp_land_max": 31.1020751953125,
"Rel_humidity": 78.8110540707906,
"Snow_depth": 0.0,
"Rain": {
"02h": 0.0,
"05h": 0.0,
"08h": 0.0,
"11h": 0.0078125,
"14h": 0.0,
"17h": 0.0,
"20h": 0.0,
"23h": 0.0
},
"Windspeed": {
"02h": 1.82151740160629,
"05h": 1.67320577035963,
"08h": 2.11051812658853,
"11h": 3.13695273037663,
"14h": 3.03581256571959,
"17h": 4.88290761284617,
"20h": 5.28992788085383,
"23h": 2.96910633106339
}
},
{
"Date": "2021-07-22",
"Temp_air_min": 21.9217163085938,
"Temp_air_max": 30.8077331542969,
"Temp_land_min": 23.2234436035156,
"Temp_land_max": 30.8184448242188,
"Rel_humidity": 80.5156491200129,
"Snow_depth": 0.0,
"Rain": {
"02h": 0.0,
"05h": 0.0,
"08h": 0.0,
"11h": 0.0,
"14h": 0.0,
"17h": 0.078125,
"20h": 0.03125,
"23h": 0.0
},
"Windspeed": {
"02h": 1.32443078240164,
"05h": 0.884845320914808,
"08h": 1.27857637974169,
"11h": 2.96615927315123,
"14h": 3.34471648783422,
"17h": 4.86611302800963,
"20h": 4.61473389447792,
"23h": 3.11187375011828
}
},
{
"Date": "2021-07-23",
"Temp_air_min": 22.8076416015625,
"Temp_air_max": 29.9495178222656,
"Temp_land_min": 23.92666015625,
"Temp_land_max": 30.4448486328125,
"Rel_humidity": 82.4750289122264,
"Snow_depth": 0.0,
"Rain": {
"02h": 0.0,
"05h": 0.0,
"08h": 0.015625,
"11h": 0.0,
"14h": 0.109375,
"17h": 0.296875,
"20h": 0.09375,
"23h": 0.015625
},
"Windspeed": {
"02h": 1.9846956883523,
"05h": 1.52067474436274,
"08h": 2.59265957326973,
"11h": 3.38407304525856,
"14h": 4.30434802079466,
"17h": 4.59953924020642,
"20h": 4.17177506280205,
"23h": 2.78244845844354
}
}
]