REST API¶
La piattaforma Radar-DPC include uno stack di servizi Representational State Transfer (REST), utilizzati nel back end dagli applicativi, ma che rappresenta anche utile API (Applicatio Program Interface) per il download dei dati Radar e più in generale per il lavoro con i servizi esposti da parte di applicazioni di terze parti.
WADL e metodi¶
L’insieme delle operazioni disponibili tramite la API è descritto nel documento WADL (Web Application Description Language).
Il punto di accesso al WADL è:
https://radar-api.protezionecivile.it/
Ispezionando il WADL è possibile notare i seguenti metodi:
Esempi di richieste¶
Si riportano di seguito alcuni esempi di richieste alla API REST, con relativa risposta da parte del servizio.
findAvailableProducts¶
Il metodo non richiede nessun parametro di input
https://radar-api.protezionecivile.it/wide/product/findAvailableProducts
Il servizio risponde con un json come il seguente, che include il numero dei prodotti disponibili ( total ) e la lista dei nomi di tali prodotti ( types ).
{
"total" : 18,
"types" : [ "CAPPI4", "CAPPI6", "CAPPI8", "SRT6", "CAPPI2", "VMI", "HRD", "CAPPI5", "TEMP", "SRT1", "SRT3", "RADAR_STATUS", "CAPPI7", "SRT24", "CAPPI1", "SRI", "CAPPI3", "SRT12" ]
}
findLastProductByType¶
Per questo metodo è necessario valorizzare il parametro di input type, assegnando uno dei valori presenti nella lista restituita dal servizio precedentemente presentato. Ad esempio:
https://radar-api.protezionecivile.it/wide/product/findLastProductByType?type=VMI
dove con l’apposizione della stringa «?type=VMI» si sta specificando il prodotto VMI.
Il servizio risponde con un json come quello mostrato di seguito
{
"total" : 1,
"lastProducts" : [ {
"productType" : "VMI",
"time" : 1640160600000,
"period" : "PT5M"
} ]
}
Il quale riporta il timestamp UTC in millisecondi (»time») dell’ultima acquisizione disponibile per il prodotto VMI. Il json riporta inoltre la periodicità di acquiszione (»period»), nell’esempio, il prodotto AMV è disponibile ogni 5 minuti.
existsProduct¶
Il servizio necessita di due paramentri di ingresso, type e time indicanti rispettivamente il tipo di prodotto e il timestamp UTC in millisecondi per il quale si voglia verificare la presenza o meno dell’acquisizione.
https://radar-api.protezionecivile.it/wide/product/existsProduct?type=VMI&time=16401606000000
Il servizio risponde con valore booleano.
downloadProduct¶
Il servizio va invocato con metodo POST, passando in input un json indicante il tipo di prodotto e il timestamp UTC in millisecondi dell’acquisizione che si voglia scaricare. Un esempio di json da utilizzare come input è il seguente:
{
"productType" : "HRD",
"productDate" : 1594023197641
}
Il servizio, a seconda del tipo di prodotto che si è richiesto, predispone l’output per il download. Nel caso di prodotti vettoriali (es. HRD) il servizio ritorna archivio contenente la collezione shapefile relativa al campione richiesto. Nel caso di raster (es. AMV) il servizio ritorna file con la copertura.
Di seguito, per scopi illustrativi, si mostra anche chiamata al servizio mediante utilità CUrl:
curl --data '{"productType":"HRD","productDate":"1572955800000"}' -H "Content-Type: application/json" -X POST https://radar-api.protezionecivile.it/wide/product/downloadProduct --output hrd.zip