API

Functions for skilled users

Specific REST APIs for data downloading, clipping and geoprocessing are developed in order to guarantee the interoperability

Downloading

The downloading is possible through GET HTTP calls that get back data from the geoDB, using a URL composed by a fixed part and a variable one.

The fixed part (BASE_URL) 

 https://droughtsdi.fi.ibimet.cnr.it/dgws/api

The variable part is composed by three different parameters: image format, image type, period. Optional parameters can be defined if users want to select only a specific polygon of interest.

Image format

  • png
  • gtiff
  • aaigrid
  • wms (coming soon)

Image type (parameter or index)

  • tci
  • vci
  • vhi
  • evhi
  • spi3
  • spi6
  • spi12

Period

  • year (year of reference)
  • month (month of reference)
  • day (day of reference)
  • doy (Julian day)

N.B.: for SPI indices the day or the doy must be the last of the month. For the other indices, the Day or the doy must correspond to the available date of satellite images.

Options (only for j_get_image)

  • polygon (extraction defining a polygon in WKT format)
  • srid_from (reference system of the polygon in EPSG code)

Syntax to download the whole image (N.B.: Only for SPI index)

The day specification is compulsory, even if we want to download monthly, weekly and two-weekly indices. The PNG images are classified, whereas the GTIFF images are saved in real. 

BASE_URL/download/j_get_image/{image_type}/{year}/{doy}/{image_format}
BASE_URL/download/j_get_whole_{image_format}/{image_type}/{year}/{doy}
BASE_URL/download/j_get_whole_{image_format}/{image_type}/{year}/{month}/{day}

Examples

  • Download of the SPI image related to doy 120 (April 30th), 2009 in PNG format 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_image/spi3/2009/120/png
  • Download of the SPI image related to May, 2009 in PNG format: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_whole_png/spi12/2009/5/31
  • Download of the SPI 3 image related to doy 243 (August 31th), 2018 in GTIFF: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_whole_gtiff/spi3/2018/243

Selecting specific polygons

Through the GET HTTP calls it is also possible to select one or more polygons in order to clip and download only some geographic portions of data. The definition of these polygons is done adding another part to the previous URL.

The clipping part 

.../polygon/POLYGON{in WKT format}/srid_from/{EPSG:code}

The new URL part is composed by two parameters: the coordinates of each polygon vertex, and the spatial reference identifier of the data in the DB.

Vertices coordinates

  • Vertices coordinates must be written in WKT format.
  • Supports polygon and multi-polygons.

Input spatial reference system

  • The spatial reference identifier must follow the EPSG (European Petroleum Survey Group) Geodetic Parameter Dataset standard and must conform to the vertices coordinates type.

Syntax to download a clipped image

The vertices coordinates must be written in WKT format.

BASE_URL/download/j_get_image/{image_type}/{year}/{doy}/{image_format}/polygon/POLYGON{in WKT format}/srid_from/{EPSG:code}
BASE_URL/download/j_get_whole_{image_format}/{image_type}/{year}/{doy}/polygon/POLYGON{in WKT format}/srid_from/{EPSG:code}
BASE_URL/download/j_get_whole_{image_format}/{image_type}/{year}/{month}/{day}/polygon/POLYGON{in WKT format}/srid_from/{EPSG:code}

Examples

  • Download of the VHI image related to May, 2009 in PNG format, clipped on Tuscany window: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_image/vhi/2009/129/png/polygon/POLYGON((9.5%2044.6,12.5%2044.6,12.5%2042.0,9.5%2042.0,9.5%2044.6))/srid_from/4326/
  • Download of the SPI 6 image related to February, 2019 in GTIFF format, clipped on Italy window: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_whole_gtiff/spi6/2019/2/28/polygon/POLYGON((6%2047.5,19%2047.5,19%2036,6%2036,6%2047.5))/srid_from/4326/

Basic spatial statistics

Through the GET HTTP calls, it is possible to calculate basic geographic statistics (mean, minimum, maximum, standard deviation, number of pixels, 25° and 75° quantiles) of a defined polygon or a specific pixel, for each time period. The results are in .json or .csv formats.

Syntax to calculate basic geographic statistics

The vertices coordinates must be written in WKT format. Outputs can have .json or .txt formats.

BASE_URL/calculate/{output_format}/{image_type}/polygon/POLYGON{in WKT format}/srid_from/{EPSG:code}

The new URL part is composed by four parameters: the output format, the image type, the coordinates of each polygon vertex, and the spatial reference identifier of the data in the DB.

Vertices coordinates

  • Vertices coordinates must be written in WKT format.

Input spatial reference system

  • The spatial reference identifier must follow the EPSG (European Petroleum Survey Group) Geodetic Parameter Dataset standard and must conform to the vertices coordinates type.

Examples

  • Statistics calculation of the VHI index related to Tuscany window, in .json format: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/calculate/series/vhi/polygon/POLYGON((9.5%2044.6,12.5%2044.6,12.5%2042.0,9.5%2042.0,9.5%2044.6))/srid_from/4326
  • Statistics calculation of the SPI12 index related to a point, in .txt (csv) format: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/calculate/seriescsv/spi12/polygon/POINT(10.0%2042.6)/srid_from/4326