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)

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

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 VHI image related to doy 97, 2009 in PNG format: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_image/vhi/2009/97/png
  • Download of the VHI image related to May, 2009 in PNG format: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_whole_png/vhi/2009/5/1
  • Download of the SPI 3 image related to doy 209, 2009 in GTIFF: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_whole_gtiff/vhi/2018/209

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 of a defined polygon (mean, minimum, maximum, standard deviation, number of pixels, 25° and 75° quantiles) for each time period. Results are in json format.

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