Satellite Imagery


large grey blob in background

Satellite Imagery API

The Satellite Imagery API is a 2-step 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 the result, you get metadata and a list of API calls (as URLs) for available products (True Color, False Color, NDVI, EVI, EVI2, NRI, DSWI, and NDWI).

  • 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, EVI2, NRI, DSWI, and NDWI indices of a polygon

    - an image in GeoTIFF format.


Step 1. Search satellite images for a polygon

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, EVI2, NRI, DSWI and NDWI indices of polygon and the image in Tiff format.


Example of 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=2504213200

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

Name of data source 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": 1502323200,
    "type": "Landsat 8",
    "dc": 100,
    "cl": 1.84,
    "sun": {
      "elevation": 60.583,
      "azimuth": 132.928
    },
    "image": {
      "truecolor": "http://api.agromonitoring.com/image/1.0/000598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "falsecolor": "http://api.agromonitoring.com/image/1.0/010598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "ndvi": "http://api.agromonitoring.com/image/1.0/020598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "evi": "http://api.agromonitoring.com/image/1.0/030598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "evi2": "http://api.agromonitoring.com/image/1.0/040598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "nri": "http://api.agromonitoring.com/image/1.0/050598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "dswi": "http://api.agromonitoring.com/image/1.0/060598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "ndwi": "http://api.agromonitoring.com/image/1.0/070598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a"
    },
    "tile": {
      "truecolor": "http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/
      000598ba200/5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "falsecolor": "http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/
      010598ba200/5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "ndvi": "http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/
      020598ba200/5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "evi": "http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/
      030598ba200/5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "evi2": "http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/
      040598ba200/5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "nri": "http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/
      050598ba200/5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "dswi": "http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/
      060598ba200/5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "ndwi": "http://api.agromonitoring.com/tile/1.0/{z}/{x}/{y}/
      070598ba200/5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a"
    },
    "stats": {
      "ndvi": "http://api.agromonitoring.com/stats/1.0/023598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "evi": "http://api.agromonitoring.com/stats/1.0/033598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "evi2": "http://api.agromonitoring.com/stats/1.0/043598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "nri": "http://api.agromonitoring.com/stats/1.0/053598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "dswi": "http://api.agromonitoring.com/stats/1.0/063598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "ndwi": "http://api.agromonitoring.com/stats/1.0/073598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a"
    },
    "data": {
      "truecolor": "http://api.agromonitoring.com/data/1.0/001598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "falsecolor": "http://api.agromonitoring.com/data/1.0/011598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "ndvi": "http://api.agromonitoring.com/data/1.0/022598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "evi": "http://api.agromonitoring.com/data/1.0/032598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "evi2": "http://api.agromonitoring.com/data/1.0/042598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "nri": "http://api.agromonitoring.com/data/1.0/052598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "dswi": "http://api.agromonitoring.com/data/1.0/062598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a",
      "ndwi": "http://api.agromonitoring.com/data/1.0/072598ba200/
      5baccca22b26590008d4da78?appid=63b351d5237d3a4232fe96f45c49671a"
    }
},
      …
] 
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 PNG format

  • 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)
  • evi2 — API call to get EVI2 (PNG)
  • nri — API call to get NRI (PNG). Available only for Landsat-8.
  • dswi — API call to get DSWI (PNG). Available only for Landsat-8.
  • ndwi — API call to get NDWI (PNG). Available only for Landsat-8.
  • 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)
  • evi2 — API call to get EVI2 (PNG)
  • nri — API call to get NRI (PNG). Available only for Landsat-8.
  • dswi — API call to get DSWI (PNG). Available only for Landsat-8.
  • ndwi — API call to get NDWI (PNG). Available only for Landsat-8.
  • stats

Get metadata for indices NDVI, EVI, EVI2, NRI, DSWI, and NDWI.

  • ndvi — API call to get metadata for NDVI index for your polygon.
  • evi — API call to get metadata for EVI index for your polygon.
  • evi2 — API call to get metadata for EVI2 index for your polygon.
  • nri — API call to get metadata for NRI index for your polygon. Available only for Landsat-8.
  • dswi — API call to get metadata for DSWI index for your polygon. Available only for Landsat-8.
  • ndwi — API call to get metadata for NDWI index for your polygon. Available only for Landsat-8.
  • data

API calls to get image for a polygon 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
  • evi2 — API call to get EVI2 (GeoTIFF), single band
  • nri — API call to get NRI (GeoTIFF), single band. Available only for Landsat-8.
  • dwsi — API call to get DSWI (GeoTIFF), single band. Available only for Landsat-8.
  • ndwi — API call to get NDWI (GeoTIFF), single band. Available only for Landsat-8.

Step 2. Get satellite images and metadata

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

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:

map response image

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 get 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


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

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, EVI, EVI2, NRI, DSWI, and NDWI.

  • 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"

This API call is a part of the response of the Satellite Imagery Search API. It is available only for NDVI, EVI, EVI2, NRI, DSWI, and NDWI 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 inde

  • 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"

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, EVI, EVI2, NRI, DSWI, and NDWI. The dataset depends on the type of preset.

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

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

Default Palette:

paletteid=1

Green palette, the common NDVI palette. Control points: (0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 1)

agro-palette-1

Technical palette:

paletteid=2

Black & white, to set your colours. Control points: (0, 1)

agro-palette-2

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)

agro-palette-3

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)

agro-palette-3




2012 - 2022 AgroMonitoring © All rights reserved