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. 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 poligono 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 ad uno specifico punto, in formato csv (.txt): 
https://droughtsdi.fi.ibimet.cnr.it/dgws/api/calculate/seriescsv/spi12/polygon/POINT(10.0%2042.6)/srid_from/4326