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

https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_image/spi3/2009/120/png
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_whole_png/spi12/2009/5/31
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

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/
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, 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

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
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/calculate/seriescsv/spi12/polygon/POLYGON((12.366%2041.99,12.63%2041.99,12.63%2041.795,12.366%2041.795,12.366%2041.99))/srid_from/4326