Guida per gli sviluppatori

Il Portale espone i suoi dati mettendo a disposizione una serie di servizi web che possono essere invocati da applicazioni esterne. Questa pagina raccoglie i servizi disponibili al pubblico e le istruzioni per il loro utilizzo.

Istruzioni generali

Se non diversamente specificato, i servizi si invocano con normali requeste di tipo GET su protocollo https, con i parametri inclusi direttamente nell'URL. I risultati sono rappresentati in formato JSON.

Feed RSS avanzati

Prima di integrare un servizio web, vale la pena considerare se sia possibile soddisfare le proprie esigenze con uno strumento più immediato. Il portale espone, per tutte le tipologie documentali pubblicate, un feed RSS avanzato che consente di filtrare i documenti secondo una serie di criteri: ad esempio, le allerte per evento, zona o comune, oppure i documenti di monitoraggio per bacino.

Per utilizzare i feed RSS avanzati, basta visitare una delle pagine relative agli archivi documentali:

Da qui, impostando il filtro desiderato e cliccando sul tasto "Aggiorna", il pulsante "RSS" presente sotto la lista dei risultati conterrà un link permanente a un feed RSS filtrato secondo gli stessi criteri.

Webservice stato e documento di allertamento

URL

https://allertameteo.regione.emilia-romagna.it/datiTempoReale-prevPiog-portlet/get-stato-allerta

Parametri
  • data (opzionale): timestamp in formato YYYY-MM-DD HH:mm, ad esempio "2022-01-09%2015:00" per indicare il 9 gennaio 2022 alle ore 15:00 (%20 è la codifica ASCII dello spazio vuoto.)
Risultato di esempio
{"dataEmissione":"gen 8, 2022 11:46:05 AM","titolo":"Allerta 005\/2022 valida dalle 00:00 del 09-01-2022: neve","link":"\/documents\/20181\/1867928\/allerta005_2022.pdf","G1":{"ghiaccio_pioggia_gela":"green","idraulica":"green","idrogeologica":"green","mareggiate":null,"neve":"green","nome":null,"stato_mare":null,"temperature_estreme":"green","temporali":"green","vento":"green"}, .... , "dataInizio":"gen 9, 2022 12:00:00 AM","tendenza":"attenuazione","descrizionemeteo":"Per la giornata di domenica 9 gennaio sono previste sul settore orientale nevicate di debole\/moderata intensità (localmente le precipitazioni potrebbero assumere condizioni di acqua mista a neve) con accumuli intorno ai 5-10 cm per le zone di collina e localmente di pianura e punte superiori ai 15 cm per le zone di montagna. Nevicate più deboli e di breve durata potranno interessare le restanti aree. Sono inoltre previsti fino al primo mattino sul crinale appenninico venti forti da sud-ovest con possibili temporanei rinforzi o raffiche di intensità superiore."}

 

Descrizione

Questo servizio restituisce lo stato dell'allertamento in un dato istante. Questo include il documento di allertamento valido al tempo specificato, con informazioni sui codici colore nelle varie zone di allertamento. Se il parametro data non è specificato, si intende il momento della chiamata. Visto che solitamente i documenti sono emessi per il giorno successivo, è normale che sia restituito un documento emesso nella giornata precedente. I codici colore per ogni zona di allertamento sono espressi con una delle seguenti stringhe: green,yellow,orange,red oppure lasciati a null quando non applicabili, ad esempio rischio mareggiate in una zona interna.

Webservice allerta in formato CAP (XML)

URL

https://allertameteo.regione.emilia-romagna.it/o/xmlcap

Parametri
  • data (opzionale): timestamp in formato YYYY-MM-DD HH:mm, ad esempio "2022-01-09%2015:00" per indicare il 9 gennaio 2022 alle ore 15:00 (%20 è la codifica ASCII dello spazio vuoto.)
Risultato di esempio
<alert xmlns="urn:oasis:names:tc:emergency:cap:1.2"> <identifier>005/2022</identifier> <sender>AllertaMeteoER@regione.emilia-romagna.it</sender> <sent>2022-01-08T11:46:05.945+01:00[Europe/Rome]</sent> <status>Actual</status> <msgType>Alert</msgType> <source>Operator</source> <scope>Public</scope> <note>Per la giornata di domenica 9 gennaio sono previste sul settore orientale nevicate di debole/moderata intensità (localmente le precipitazioni potrebbero assumere condizioni di acqua mista a neve) con accumuli intorno ai 5-10 cm per le zone di collina e localmente di pianura e punte superiori ai 15 cm per le zone di montagna. Nevicate più deboli e di breve durata potranno interessare le restanti aree. Sono inoltre previsti fino al primo mattino sul crinale appenninico venti forti da sud-ovest con possibili temporanei rinforzi o raffiche di intensità superiore.</note> <info> <language>it-IT</language> <category>Geo</category> <event>GIALLO</event> <responseType>Prepare</responseType> <urgency>Expected</urgency> <severity>Moderate</severity> <certainty>Likely</certainty> <onset>2022-01-09T00:00+01:00[Europe/Rome]</onset> <expires>2022-01-10T00:00+01:00[Europe/Rome]</expires> <parameter> <valueName>IDRAULICO</valueName> <value>VERDE</value> </parameter> <parameter> <valueName>IDROGEOLOGICO</valueName> <value>VERDE</value> </parameter> <parameter> <valueName>TEMPORALI</valueName> <value>VERDE</value> </parameter> <parameter> <valueName>VENTO</valueName> <value>VERDE</value> </parameter> <parameter> <valueName>TEMPERATURE_ESTREME</valueName> <value>VERDE</value> </parameter> <parameter> <valueName>NEVE</valueName> <value>GIALLO</value> </parameter> <parameter> <valueName>GHIACCIO_PIOGGIA_CHE_GELA</valueName> <value>VERDE</value> </parameter> <parameter> <valueName>STATO_MARE</valueName> <value/> </parameter> <parameter> <valueName>MAREGGIATE</valueName> <value/> </parameter> <area> <areaDesc>Emil-A1</areaDesc> </area> </info> ... </alert>

 

Descrizione

Il servizio restituisce il documento di allertamento valido all'istante specificato, o l'istante attuale se invocato senza parametro. Il formato di output è il Common Alerting Protocol (CAP), uno standard in materia di interscambio dati di allertamento. Deve essere interpretato con un lettore XML.

Webservice stato e documento valanghe

URL

https://allertameteo.regione.emilia-romagna.it/o/api/stato-valanghe

Parametri
  • data (opzionale): timestamp in formato YYYY-MM-DD HH:mm, ad esempio "2022-01-09%2015:00" per indicare il 9 gennaio 2022 alle ore 15:00 (%20 è la codifica ASCII dello spazio vuoto.)
Risultato di esempio
{"appennino_centrale":"green","descrizione":"Gli scenari di riferimento sono consultabili nella Tabella scenari valanghe.\n\nPer approfondimenti sulla situazione neve e valanghe è possibile consultare il Bollettino Meteomont sul sito del Servizio METEOMONT dell'Arma dei Carabinieri","titolo":"Bollettino valanghe 008\/2022 valido dalle 00:00 del 09\/01\/2022","appennino_romagnolo":"green","datainizio":"gen 9, 2022 12:00:00 AM","appennino_occidentale":"green","datafine":"gen 10, 2022 12:00:00 AM"}

 

Descrizione

Questo servizio restituisce lo stato dell'allertamento valanghe in un dato istante. Questo include il documento valanghe valido al tempo specificato, con informazioni sui codici colore nelle tre zone (Appennino Occidentale, Centrale e Romagnolo). Se il parametro data non è specificato, si intende il momento della chiamata. Visto che solitamente i documenti sono emessi per il giorno successivo, è normale che sia restituito un documento emesso nella giornata precedente. I codici colore per ogni zona valanghe sono espressi con uno dei seguenti codici: green,yellow,orange,red oppure lasciati a null quando non applicabili, ad esempio per mancanza del dato previsionale.

NB: Il bollettino/allerta Valanghe viene emesso nel periodo che solitamente va da novembre ad aprile ma può variare secondo le condizioni meteo-nivometriche della stagione in corso.

Webservice ultimi documenti di monitoraggio

URL

https://allertameteo.regione.emilia-romagna.it/datiTempoReale-prevPiog-portlet/get-bollettino-monitoraggio

Parametri

Nessuno

Risultato di esempio
{"001\/2021\/09 ULTIMO":{"bacino":[{"comuni":["ALFONSINE(RA)","ALTO RENO TERME(BO)","ARGELATO(BO)","ARGENTA(FE)","BARICELLA(BO)","BOLOGNA(BO)","CALDERARA DI RENO(BO)","CAMUGNANO(BO)","CASALECCHIO DI RENO(BO)","CASTEL DI CASIO(BO)","CASTELLO D'ARGILE(BO)","CASTEL MAGGIORE(BO)","CASTIGLIONE DEI PEPOLI(BO)","CENTO(FE)","COMACCHIO(FE)","CONSELICE(RA)","GAGGIO MONTANO(BO)","GALLIERA(BO)","GRIZZANA MORANDI(BO)","MALALBERGO(BO)","MARZABOTTO(BO)","MOLINELLA(BO)","MONZUNO(BO)","PIEVE DI CENTO(BO)","POGGIO RENATICO(FE)","RAVENNA(RA)","SALA BOLOGNESE(BO)","SAN BENEDETTO VAL DI SAMBRO(BO)","SAN GIORGIO DI PIANO(BO)","SAN GIOVANNI IN PERSICETO(BO)","SAN PIETRO IN CASALE(BO)","SASSO MARCONI(BO)","TERRE DEL RENO(FE)","VERGATO(BO)"],"nome_bacino":"RENO","province":["RA","BO","FE"],"sottobacino":[{"colmo_previsto":{"dataOra":"19:00","valore":"15,36"},"nomeSottobacino":"Gandazzolo Reno","osservazione":{"dataOra":"11:30","valore":"15.0"}},{"colmo_previsto":{"dataOra":null,"valore":null},"nomeSottobacino":"Gallo","osservazione":{"dataOra":"11:30","valore":"11.28"}},{"colmo_previsto":{"dataOra":"mattina","valore":"~soglia1"},"nomeSottobacino":"Ponte Bastia","osservazione":{"dataOra":"11:00","valore":"7.73"}}]},{"comuni":["BAISO(RE)","BASTIGLIA(MO)","BOMPORTO(MO)","CAMPOGALLIANO(MO)","CARPI(MO)","CARPINETI(RE)","CASALGRANDE(RE)","CASTELLARANO(RE)","CASTELNOVO NE' MONTI(RE)","CAVEZZO(MO)","CONCORDIA SULLA SECCHIA(MO)","FORMIGINE(MO)","FRASSINORO(MO)","LAMA MOCOGNO(MO)","MODENA(MO)","MONTEFIORINO(MO)","NOVI DI MODENA(MO)","PALAGANO(MO)","POLINAGO(MO)","PRIGNANO SULLA SECCHIA(MO)","REGGIO NELL'EMILIA(RE)","RUBIERA(RE)","SAN POSSIDONIO(MO)","SAN PROSPERO(MO)","SASSUOLO(MO)","SCANDIANO(RE)","SOLIERA(MO)","TOANO(RE)","VENTASSO(RE)","VIANO(RE)","VILLA MINOZZO(RE)"],"nome_bacino":"SECCHIA","province":["RE","MO"],"sottobacino":[{"colmo_previsto":{"dataOra":null,"valore":null},"nomeSottobacino":"Ponte Motta","osservazione":{"dataOra":"11:00","valore":"8.11"}},{"colmo_previsto":{"dataOra":null,"valore":null},"nomeSottobacino":"Pioppa","osservazione":{"dataOra":"11:30","valore":"9.08"}},{"colmo_previsto":{"dataOra":"12:00","valore":"10,27"},"nomeSottobacino":"Concordia sulla Secchia","osservazione":{"dataOra":"11:30","valore":"9.01"}}]}],"fineMonitoraggio":"gen 26, 2021 12:00:00 AM","inizioMonitoraggio":"gen 25, 2021 12:00:00 PM","link":"\/documents\/20181\/1634354\/monitoraggio001_2021_09 ULTIMO.pdf","note":"La piena di Secchia sta defluendo regolarmente nel tratto terminale di valle, in lenta diminuzione, sotto la soglia 2. Entro la giornata di domani mattina i livelli di valle rientreranno anche sotto la soglia 1.\nIl colmo della piena di Reno in laminazione, sta transitando dalla sezione di Bastia con soglia prossima a 1. \nI livelli delle sezioni arginate di monte, in lenta diminuzione, rientreranno entro la giornata di domani mattina progressivamente sotto la soglia 1.\nSono previste ancora precipitazioni deboli sui settori orientali della regione, a carattere nevoso in appennino sopra i 700m.","titolo":null}, ... }

 

Descrizione

Questo servizio restituisce gli ultimi 10 documenti di monitoraggio emessi. Le informazioni disponibili riproducono l'intero stato del documento, inclusi i bacini, sensori e comuni coinvolti.

Badge del Portale Allerte

Descrizione

Il portale mette a disposizione una serie di badge che possono essere inclusi in un sito web per mostrare dettagli sullo stato di allertamento provenienti dal sito ufficiale. Sono disponibili vari template con diversi livelli di dettaglio, alcuni dei quali possono essere parametrizzati su un singolo Comune di interesse.

Come utilizzare il servizio

L'embedding del badge avviene tramite iniezione dinamica di un elemento HTML, e non con iframe. Per questo motivo, la pagina che desidera effettuare l'embedding deve includere il link al seguente file javascript:

https://allertameteo.regione.emilia-romagna.it/o/badge.js

 

Questo potrebbe richiedere permessi aggiuntivi sul dominio del portale in un eventuale header Content-Security-Policy.

 

Per generare il badge basta a questo punto inserire il seguente codice nel punto dove lo si vuol far comparire.

<div class="allerta-meteo" tipo="TEMPLATE"> <div>

 

Al posto di TEMPLATE va indicato il tipo di badge che si desidera includere, scegliendolo tra i seguenti:

 

  • minimal - questo template genera un badge con le sole informazioni sul colore del bollettino/allerta valido al momento della richiesta, e i relativi documenti emessi.
  • fenomeni - questo template genera un badge che, in aggiunta alle informazioni del template minimal, mostra i codici colore massimi per ognuno dei fenomeni oggetto di allertamento, incluse le valanghe.
  • mappa - questo template genera un badge che include anche una mappa della Regione con i codici colore massimi per zona di allertamento, mostrando una vista che richiama la home page del portale.

I template minimal e fenomeni possono inoltre prendere un parametro opzionale comune. Questo parametro va valorizzato con il codice ISTAT del Comune di interesse, per mostrare i codici colore relativi al solo Comune. Ad esempio, per includere il badge dei fenomeni relativi al Comune di Bologna, il codice sarebbe il seguente.

<div class="allerta-meteo" tipo="fenomeni" comune="037006"> <div>