Dive into Agro API | Part 4 – Satellite Imagery

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