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)

N.B.: per l’indice SPIil giorno o il doy va indicato l’ultimo giorno del mese. Per gli altri indici, il giorno o il doy devono corrispondere con il giorno per cui sono disponibili le immagini satellitari.

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 (N.B.: solo per indici SPI)

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 SPI relativa al giorno giuliano 120 (30 Aprile), del 2018 in formato PNG: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_image/spi12/2018/120/png
  • Scarico dell'immagine SPI relativa a Maggio, 2018 in formato PNG: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_whole_png/spi6/2018/5/31
  • Scarico dell'immagine SPI relativa al giorno giuliano 243 (31 Agosto), del 2018 in formato GTIFF: 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/download/j_get_whole_gtiff/spi3/2018/243

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 (media, valori minimo e massimo, deviazione standard, numero di pixel, 25° e 75° quantile) di un poligono definito, lungo la serie storica. I risultati sono rilasciati in formato .json o .csv.

Sintassi per il calcolo delle statistiche spaziali di base

Le coordinate dei vertici del poligono devono essere scritte in formato WKT. Il formato di output può essere .json o .txt.

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

La nuova parte di URL è composta da quattro parametri: il formato di output, 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.

Esempi

  • Calcolo delle statistiche dell'indice VHI relative al rettangolo che include la Toscana, in formato .json: 
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
  • Calcolo delle statistiche dell'indice SPI12 relative al rettangolo che include la città di Roma, in formato csv (.txt): 
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