Dive into Agro API | Part 4 – Satellite Imagery
Posted on 21 Jan 2020
The Satellite Imagery API is a part of our Agriculture API (Agro API) for the agricultural sector.
OpenWeather provides satellite data for user-defined polygon in the format of images in true colour, false colour, NDVI and EVI indices, and of NDVI and EVI statistical data. To obtain them we suggest using our Satellite Imagery API.
Step 1. How to start?
Your personal API key and polygon ID are required to find and retrieve the desired satellite data.
Creation and removal of polygons are described in one of the previous articles “Dive into Agro API | Part 2 – Polygons”.
Step 2. How to get data? GET request and its parameters.
At this stage, we are searching for your polygon among all available satellite images.
Make an HTTP GET request to Agro API using your API key and polygon ID.
Format of the API request:
http://api.agromonitoring.com/agro/1.0/image/search?start={start}&end={end}&polyid={polyid}&appid={appid},
Required parameters:
appid - your “API Key” (link to the first article)
polyid - your polygon ID (link to the second article)
start – beginning of requested period in UTC format
end - end of requested period in UTC format
Please note: if you specify a short period of time (from the 'start' to 'end'), then you may not receive the data by your polygon. According to the documentation of Sentinel-2 periodicity of scanning depends on the latitude and vary from 3 to 5 days. For Landsat-8 periodicity is 16 days.
Additional parameters can be used in the request:
type - Satellite data source: “L8” in upper case, “s2” in lower case.
The percentage of the polygon area with available data:
coverage_max% - maximum percentage
coverage_min% - minimum percentage
The percentage of the area cloud covered:
clouds_max% - maximum percentage
clouds_min% - minimum percentage
Pixels per meter resolution:
resolution_max - maximum density
resolution_min - minimum density
Using these parameters, you can specify the maximum and / or minimum pixel to meter resolution.
Step 3. Response of the GET request. Description of the primary parameters.
The response data contain a group with primary parameters with metadata and 4 URL groups: “image”, “tile”, “stats” and “data” (see also Step 4 ). Each URL group includes links to satellite images and metadata.
Here is a sample of response data in JSON format (Img. 1):
Img. 1. Response in JSON format
Example of the group with primary parameters in the response data:
Img. 2. Primary parameters
Description of the primary parameters:
dt - satellite scene acquisition time in UTC Unix format
type - satellite data source: Landsat-8 or Sentinel-2
dc - approximate percentage of area covered by polygon
cl - approximate cloud cover percentage
sun - the solar position at the acquisition time. If several scenes fall into the resulting data, then the last section will be sent
azimuth - azimuth of the Sun
elevation – altitude of the Sun
URL groups: “image”, “tile”, “stats” and “meta”
image – URL links to images with your polygon in PNG format
Img. 3. Parameters of “image” group
tile – URL links with your polygon in PNG format for a tile service
Img. 4. Parameters of “tile” group
data - URL links to images with your polygon in TIFF format
Img. 5. Parameters of “data” group
stats – URL links to statistics for your polygon
Img. 6. Parameters of “stats” group
Description of parameters in “image”, “tile” and “data” groups:
truecolour – data in RGB (red, green and blue) bands
falsecolour – data in NIR (near-infrared), green and blue bands
ndvi – normalized difference vegetation index (NDVI) in red and NIR bands
evi - enhanced vegetation index (EVI) in NIR, red and blue bands
Parameters of “stats” group
ndvi - normalized difference vegetation index statistics
evi - enhanced vegetation index statistics
Step 4. Receiving satellite images and metadata by using provided URLs. Examples and description.
Follow URL links provided in the previous step. Obtained images and metadata can be embedded in your application.
Your polygon is available as images in PNG and TIFF formats, as tiles in PNG format and metadata as NDVI and EVI indices.
4.1. Getting images in PNG format
Copy the URL from the ‘image’ group and make an API call. Your polygon will be opened in a new tab.
Example of an API request:
http://api.agromonitoring.com/image/1.0/02059768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7
Example of response:
4.2. Getting tiles with your polygon in PNG format
Copy the URLs from the ‘tile’ group and paste them into one of the popular JS libraries “OpenLayers”, “Leaflet”, etc. Any other applications supporting tile layers can be used.
If your polygon covers several tiles, then each tile layer would contain a corresponding part of the polygon. Tile layering application (Leaflet, OpenLayers) will find the correct ZXY coordinates based on the scaling and location and replace them in the provided URL templates.
Please note that if your application or JS library does not support displaying of tile layers, or the ZXY coordinates supplied were invalid, the following error will be returned: ‘code 400002, incorrect zxy coordinates’.
We have 4 preset custom palettes for NDVI images, the most practical pallets for agricultural applications:
- Green palette, the common NDVI palette - 1 (default)
- Technical palette, black & white, to set your colours - 2
- Contrast palette #1 - 3
- Contrast palette #2 - 4
To get an image of your polygon in other custom palettes, just add an additional parameter to the got URL:
paletteid - palette ID (values correspond to the list above - 1, 2, 3, 4)
Example of API request:
http://api.agromonitoring.com/image/1.0/02059768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7&paletteid=1
More information about custom palettes is here.
4.3. Getting your polygon in GeoTIFF format
Copy the URL from the ‘data’ group, make an API call and get the image of your polygon.
The following programs can be used to open the received images: GDAL, QGIS, GRASS GIS, etc.
Example of API request:
Download NDVI satellite image in GeoTIFF
http://samples.agromonitoring.com/data/1.0/02259768a00/5ac22f004b1ae4000b5b97cf?appid=b1b15e88fa797225412429c1c50c122a1
Example of response:
5. Metadata and statistics on NDVI and EVI polygon indices
Copy the URLs from the ‘stats’ group and make an API call. Metadata and statistics of your polygon will be returned.
Example of response:
Img. 7. Parameters of “ndvi” and “evi” responses
“std” - standard deviation
“p25” - the 25th percentile (first quartile) of the index
“median” - the 50th percentile (second quartile) of the index
“p75” - the 75th percentile (third quartile) of the index
“max” - The maximum value of the index
“min” - The minimum value of the index
“mean” - The average value of the index
“num” - Number of pixels in your polygon
Find out more about Agro APIs in the Documentation and Price sections.
For any queries, please contact us at info@openweathermap.org.
Dive into Agro API | Part 1 - Personal Account
Dive into Agro API | Part 2 - Polygons
Dive into Agro API | Part 3 - Historical NDVI
