Contact us
Sign in Sign up

Satellite imagery

Satellite imagery API


The Satellite Imagery API is a 2-steps API to get imagery data for your polygon. How it works:

  • Step 1. Search for satellite imagery and get metadata for a polygon.
    You make a search API call to check available satellite imageries for your polygon. In result, you get metadata and a list of API calls (as URLs) for available products (True Color, False Color, NDVI, and EVI).

  • Step 2. Get imageries and zonal statistics.
    As a result of Step 1, you have a response that contains metadata and a list of API calls for 4 groups of products: "image", "tile", "stats", and "data".
    Using API call to a particular group, you can get:
    - an image of a polygon in PNG format
    - a tile in PNG format
    - zonal statistics for NDVI & EVI indices of a polygon
    - an image in GeoTIFF format.


Step 1. Search satellite images for a polygon

Desctiption:

On this initial step we search all available satellite imageries for your polygon and return you URLs to them. URLs are organized in 4 groups - 'image', 'tile', 'stats' and 'data'. Use URLs from these 4 groups in the Step 2 to get images or metadata that you can embed to your application. Now you can get an image of your polygon in PNG, a tile in PNG format, metadata of NDVI & EVI indices of polygon and the image in Tiff format.

API call:

http://api.agromonitoring.com/agro/1.0/image/search?start={start date}&end={end date}&polyid={ID of polygon}&appid={API key}

Parameters of request:

Necessary parameters

appid Personal API key

polygon_id ID of a polygon

start Start date of the data search (unix time, UTC), e.g. start=1483218000

end End date of the data search (unix time, UTC), e.g. end=1504213200

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.

Optional parameters

resolution_min px/meters

resolution_max px/meters

type Name of datasourse Landsat-8 (l8), Sentinel-2 (s2)

coverage_max %

coverage_min %

clouds_max %

clouds_min %

Example of API request:

http://api.agromonitoring.com/agro/1.0/image/search?start=1500336000&end=1508976000&polyid=5aaa8052cbbbb5000b73ff66&appid=bb0664ed43c153aa072c760594d775a7

Example of API response:
[
   {
      "dt":1500940800,
      "type":"Landsat 8",
      "dc":100,
      "cl":1.56,
      "sun":{
         "azimuth":126.742,
         "elevation":63.572
      },
      "image":{
         "truecolor":"http://api.agromonitoring.com/image/1.0/00059768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7",
         "falsecolor":"http://api.agromonitoring.com/image/1.0/01059768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7",
         "ndvi":"http://api.agromonitoring.com/image/1.0/02059768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7",
         "evi":"http://api.agromonitoring.com/image/1.0/03059768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7"
      },
      "tile":{
         "truecolor":"http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/00059768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7",
         "falsecolor":"http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/01059768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7",
         "ndvi":"http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/02059768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7",
         "evi":"http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/03059768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7"
      },
      "stats":{
         "ndvi":"http://api.agromonitoring.com/stats/1.0/02359768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7",
         "evi":"http://api.agromonitoring.com/stats/1.0/03359768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7"
      },
      "data":{
         "truecolor":"http://api.agromonitoring.com/data/1.0/00159768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7",
         "falsecolor":"http://api.agromonitoring.com/data/1.0/01159768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7",
         "ndvi":"http://api.agromonitoring.com/data/1.0/02259768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7",
         "evi":"http://api.agromonitoring.com/data/1.0/03259768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7"
      }
   },
   {
      …
   }
]
Parameters of response:
  • dt Acquisition date (Unix time, UTC)
  • type Satellite name (Landsat 8, Sentinel 2)
  • dc Approximate percent of valid data coverage
  • cl Approximate percent of cloud coverage
  • sun Sun zenith and azimuth angles at scene acquisition time
  • image API calls to get image for a polygon in True color, False color, NDVI and EVI in PNG
    • truecolor API call to get True color (PNG)
    • falsecolor API call to get False color (PNG)
    • ndvi API call to get NDVI (PNG)
    • evi API call to get EVI (PNG)
  • tile List of API calls for use in libraries which support tile layers (Leaflet, OpenLayers, etc)
    • truecolor API call to get True color (PNG)
    • falsecolor API call to get False color (PNG)
    • ndvi API call to get NDVI (PNG)
    • evi API call to get EVI (PNG)
  • stats Get meta data for NDVI and EVI
    • ndvi API call to get meta data for NDVI index your polygon.
    • evi API call to get meta data for EVI index your polygon.
  • data API calls to get image for a polygon in True color, False color, NDVI and EVI in TIFF format
    • truecolor API call to get True color (GeoTIFF), multiband (RGB)
    • falsecolor API call to get False color (GeoTIFF), multiband
    • ndvi API call to get NDVI (GeoTIFF), single band
    • evi API call to get EVI (GeoTIFF), single band

Step 2. Get satellite images and meta data


Get image of your polygon in PNG format with "image"

Description:

This API call is a part of the response of the Satellite Imagery Search API. You can get image for your polygon in the following presets - True color, False color, NDVI and EVI.

In the Step 1 specify the ID of your polygon, the period of searching and your API key. In the API response, you will receive URLs to all availble images. Use these URLs for calling for images in PNG in True color, False color, NDVI and EVI.

Example of API request:

Get NDVI satellite image in PNG format

http://api.agromonitoring.com/image/1.0/02059768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7

Example of response:



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.



    Get tiles with your polygon in PNG format with "tile"

    Description:

    This API call is a part of the response of the Satellite Imagery Search API. You will receive a link to the tile layer for insert in the plugin or an application, if it supports to display the tile layers. Tiles are provided in the following presets - True color, False color, NDVI and EVI.

    In the Step 1 specify the ID of your polygon, the period of searching and your API key. The URL received in the response in the 'tile' (on step 1) insert into special plugins, for example Leaflet and OpenLayers, etc . Also you can use any other applications that support to display the tile layers.

  • z number of zoom level
  • x number of x tile coordinate
  • y number of y tile coordinate

    • Example of API request for insert into special plugins:

    http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/00059768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7



    Get metadata and statistics of your polygon with "stat"

    Description:

    This API call is a part of the response of the Satellite Imagery Search API. It is available only for NDVI and EVI indices.

    Example of API call:

    http://api.agromonitoring.com/stats/1.0/02359768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7

    Example of API response "stat" section:
    {
   "std":0.19696951630010479,
   "p25":0.3090659340659341,
   "num":57162,
   "min":-0.2849250197316496,
   "max":0.8658669574700109,
   "median":0.45692992317131553,
   "p75":0.6432460461498574,
   "mean":0.47631485576814037
}
    Parameters of response for a polygon:
    • std The standard deviation of the index
    • p25 The first quartile value of the index
    • num The number of pixels in the current polygon
    • min The minimum value of the index
    • max The maximum value of the index
    • median The median value of the index
    • p75 The third quartile value of the index
    • mean The average value of the index

    Get your polygon in GeoTIFF format with "data"

    Description:

    This API call is a part of the response of the Satellite Imagery Search API. You can download your polygon in GeoTIFF format in the following presets - True color, False color, NDVI and EVI.
    The data set depends on the type of preset.

    In the Step 1 specify the ID of your polygon, the period of searching and your API key.
    In the API response, you will receive URLs to download your polygon in GeoTIFF format on differen presets.
    You can use the following instrument for open downloaded file: Photoshop, QGIS, GRASS GIS, etc.

    Example of API request:

    Download NDVI satellite image in GeoTIFF

    http://api.agromonitoring.com/data/1.0/02259768a00/5ac22f004b1ae4000b5b97cf?appid=bb0664ed43c153aa072c760594d775a7


    Custom palette for NDVI images

    We have 4 preset custom palettes for NDVI images, the most practical pallets for agricultural applications:

  • Green palette, the common NDVI palette (default)
  • Technical palette, black & white, to set your colours
  • Contrast palette #1
  • Contrast palette #2

    • To get an image of your polygon in other custom palettes, just add an additional parameter to the got URL on Step 2.

    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


    Green palette, the common NDVI palette - paletteid=1 (default)

    Control points: (0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 1)

    Technical palette, black & white, to set your colours - paletteid=2

    Control points: (0, 1)

    Contrast palette #1 - paletteid=3

    Control points: (0, 0.25, 0.3, 0.35, 0.4, 0.45, 0.5, 0.55, 0.6, 0.65, 0.7, 0.75, 0.8, 0.85, 0.9, 0.95, 1)



    Contrast palette #2 - paletteid=4

    Control points: (0, 0.07, 0.15, 0.23, 0.3, 0.37, 0.45, 0.51, 0.58, 0.65, 0.7, 0.75, 0.8, 0.85, 0.9, 0.95, 1)