Functions for skilled users
Specific REST APIs for data downloading, clipping and geoprocessing are developed in order to guarantee the interoperability
We are updating the api.
New web page coming soon!
To guarantee full interoperability across the platform, a set of APIs based on the REST paradigm has been implemented.
The functions can be invoked through HTTP GET or POST calls, and the data are released in various formats that comply with OGC-approved standards.
To use the APIs, you may rely on software such as cURL or Postman, or you can implement the DO service calls directly within your own development framework (C, Java, Python, etc.).
Image types
The available functions operate on both original and derived datasets stored in the Drought Central main database. Below are the products accessible through the APIs and their corresponding tags to be used in service calls.
Image type (parameter or index)
- spi1
- spi3
- spi6
- spi12
- surface temperature anomalies
Tags
- spi1
- spi3
- spi6
- spi12
- spi24
- skintemp_anomalies
"Access token" and "Refresh token"
All API calls must include an Access token in the request header.
The Access token is valid for ten minutes, after which it must be refreshed using the Refresh token.
The first time you invoke a service—or whenever both tokens have expired—you must call the user authentication service, as described below.
Token Generation
Call type: POST
url : https://dows.ibe.cnr.it:8443/dows-2-0/api/authentication/user
Function invoked to generate a valid Access token and Refresh token for the active user account:
- Parameters (description)
- Username: user’s email
- Password: password
Parameters must be passed as the entity body of the request (FORM URLENCODED). This function will generate a new Access token and a new Refresh token.
The new Access token will be valid for ten minutes, after which it must be regenerated via a new API call (see below). Its Refresh period lasts twenty days; once this period expires, the session ends and the user service must be called again to regenerate both tokens.
A successful authentication returns a JSON object containing the two tokens. The JSON has the following structure:
Object (meaning):
- access_token
- refresh_token
If authentication fails, the message “Unauthorized” is returned.
Request example
curl -X POST –data ‘username=name.surname@xxx.it‘ –data ‘password=XXXXXX’ -H ‘Content-Type: application/x-www-form-urlencoded’https://agrosatws.ibe.cnr.it:8443/dows-2.0/api/authentication/user
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
- Statistics calculation of the VHI index related to Tuscany window, in .json format:
https://droughtsdi.fi.ibimet.cnr.it/dgws2/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 Rome window, in .txt (csv) format:
https://droughtsdi.fi.ibimet.cnr.it/dgws2/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 