API

Funzioni Avanzate

API REST specifiche per le operazioni di download, clipping e geoprocessing, per garantire l’interoperabilità dei dati

Come fare il Download

Lo scarico è possibile attraverso chiamate GET HTTP che restituiscono dati dal GeoDB, usando una URL composta da una parte fissa e da una variabile.

La parte fissa (BASE_URL) 

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

La parte variabile è composta da tre diversi parametri: il formato dell’immagine, il tipo di immagine e il periodo. I parametri opzionali possono essere definiti se si vuole selezionare un poligono specifico di interesse per l’utente.

Formato immagine

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

Tipo di immagine (parametro o indice)

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

Periodo

  • anno (anno di riferimento)
  • mese (mese di riferimento)
  • giorno (giorno di riferimento)
  • doy (giorno Giuliano)

Opzioni (solo per j_get_image)

  • polygon (estrazione definendo un poligono in formato WKT)
  • srid_from (sitema di riferimento del poligono in codice EPSG)

Sintassi per il download dell'intera immagine

La definizione del giorno è obbligatoria, anche se si vogliono scaricare indici con risoluzione temporale mensile, settimanale o bi-settimanale. Le immagini PNG sono classificate, mentre quelle GTIFF sono salvate in formato 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}

Esempi

  • Scarico dell'immagine VHI relativa al giorno giuliano 97, del 2018 in formato PNG: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_image/vhi/2018/97/png
  • Scarico dell'immagine VHI relativa a Maggio, 2018 in formato PNG: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_whole_png/vhi/2018/5/1
  • Scarico dell'immagine VHI relativa al giorno giuliano 209, del 2018 in formato GTIFF: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_whole_gtiff/vhi/2018/209

Selezionare specifici poligoni

Tramite chiamate GET HTTP è anche possibile selezionare uno o più poligoni per ritagliare e scaricare solo dati di specifiche porzioni geografiche. La definizione di tali poligoni avviene aggiungendo un’altra parte alla URL precedentemente descritta.

La parte di ritaglio 

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

La nuova parte di URL è composta da due parametri: le coordinate di ciascun vertice del poligono, e l’identificativo spaziale di riferimento dei dati nel GeoDB.

Coordinate dei vertici

  • Le coordinate dei vertici devono essere indicate nel formato WKT.
  • Supporta il singolo poligono e un multi-poligono.

Sistema di riferimento spaziale

  • L’identificativo spaziale di riferimento deve seguire lo standard EPSG (European Petroleum Survey Group) Geodetic Parameter Dataset e deve essere concorde con il tipo di coordinate dei vertici.

Sintassi per il download di un'immagine ritagliata

Le coordinate dei vertici del poligono devono essere scritte in formato WKT.

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}

Esempi

  • Download dell'immagine VHI di Maggio, 2018 in formato PNG, ritagliata sulla finestra della Toscana: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_image/vhi/2018/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 dell'immagine SPI 6 di Febbraio, 2019 in formato GTIFF, ritagliata sulla finestra dell'Italia: 
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/

Statistiche spaziali di base

Tramite chiamate GET HTTP è possibile calcolare statistiche geografiche di base di un poligono definito (media, valori minimo e massimo, deviazione standard, numero di pixel, 25° e 75° quantile) lungo la serie storica. I risultati sono in formato json.

Sintassi per il calcolo delle statistiche spaziali di base

Le coordinate dei vertici del poligono devono essere scritte in formato WKT.

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

La nuova parte di URL è composta da tre parametri: il tipo di immagine, le coordinate di ciascun vertice del poligono, e l’identificativo spaziale di riferimento dei dati nel GeoDB.

Coordinate dei vertici

  • Le coordinate dei vertici devono essere indicate nel formato WKT.

Sistema di riferimento spaziale

  • L’identificativo spaziale di riferimento deve seguire lo standard EPSG (European Petroleum Survey Group) Geodetic Parameter Dataset e deve essere concorde con il tipo di coordinate dei vertici.

Esempio

  • Calcolo delle statistiche dell'indice VHI relative al poligono che include la Toscana: 
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