Esistono tre diversi modi per scaricare i dati dal portale MeteoHub: Interfaccia Web, Client MeteoHub e API.

1. Interfaccia Web

Un utente registrato può ottenere dati da uno o più dataset della piattaforma utilizzando la funzione Data Extraction tramite l’interfaccia web di MeteoHub.

Come utilizzare la funzione di estrazione dati

Nella prima fase, l’utente deve selezionare uno o più set di dati. La selezione multipla è consentita solo con set di dati della stessa categoria (osservazione, previsione, radar) e aventi licenza compatibile.

Nel secondo passaggio, l’utente può filtrare rispettando i parametri specifici per la categoria del set di dati:

Se all’utente è consentito utilizzare strumenti di post-elaborazione, questi possono essere applicati nel terzo passaggio. Il set di strumenti di post-elaborazione è specifico per la categoria del set di dati:

Nel quarto e ultimo passaggio, l’utente deve immettere un nome per la richiesta corrente e inviare la richiesta al sistema. Prima di inoltrare la richiesta, è anche possibile programmarla utilizzando il pulsante “Pianifica”.

Dopo aver inviato una richiesta, l’utente viene indirizzato alla pagina “Le mie richieste” dove, una volta completata l’estrazione, è possibile scaricare i dati di output.

Un video tutorial che illustra le quattro fasi di costruzione e presentazione della richiesta, e uno con ulteriori informazioni sull’estrazione dei dati, sono disponibili qui:

Come scaricare pacchetti di dati open

Per tutti gli utenti, anche quelli non loggati, è possibile scaricare pacchetti di open data. I pacchetti vengono prodotti quotidianamente e sono disponibili qui.

Attualmente questa funzionalità è disponibile per i seguenti dataset:

• ICON-2I | surface and pressure levels
• BOLAM-ISAC
• MOLOCH-ISAC
• SWAN-ITA
• SWAN-MED
• radar_dpc
• WRF_OL
• WRF_DA_ITA

I dati open dei dataset osservativi possono essere scaricati dalla pagina web della mappa dei dati osservati.

2. Client MeteoHub

Un’applicazione client che consente agli utenti di eseguire le principali operazioni sulla piattaforma MeteoHub da riga di comando è disponibile in questo repository GITLab.

L’applicazione consente agli utenti di scaricare i dati estratti da una richiesta immediata o programmata preparata in modo interattivo sull’interfaccia web di MeteoHub.

Al momento, il client a riga di comando non consente di eseguire o pianificare richieste di estrazione dei dati che devono essere preparate in modo interattivo attraverso l’interfaccia web.

Un video tutorial su come utilizzare il client MeteoHub è disponibile qui:

3. API

Gli utenti possono utilizzare direttamente le API di MeteoHub (per le quali è disponibile apposita documentazione) per creare e pianificare richieste di estrazione dei dati e per scaricare i dati di output.

Come scaricare gli open data usando le API

Questa API deve essere utilizzata per ottenere l’elenco di tutti i pacchetti di dati aperti per un set di dati specifico:

• GET https://meteohub.agenziaitaliameteo.it/api/datasets/{dataset_name}/opendata

dove il parametro dataset_name corrisponde esattamente al “Dataset ID” che compare nella pagina Datasets. Attualmente questa funzionalità è disponibile per tutti i set di dati di tipo previsionale e per il set radar_dpc.

Per richiedere il download di un pacchetto specifico di dati aperti deve essere utilizzata questa API:

• GET https://meteohub.agenziaitaliameteo.it/api/opendata/{filename}

dove il parametro filename nella query corrisponde al nome del pacchetto da scaricare.

Per richiedere il download di uno o più pacchetti di dati aperti relativi a uno specifico set di dati, a una specifica data di riferimento e/o a una specifica corsa deve essere utilizzata questa API:

• GET https://meteohub.agenziaitaliameteo.it/api/opendata/{dataset_name}/download?reftime={reference_date}&run={run}

dove il parametro dataset_name corrisponde esattamente al “Dataset ID” che compare nella pagina Datasets.

La data per il campo reference_date deve essere espressa usando uno dei due seguenti formati: YYYYMMDD oppure YYYY-mm-dd dove YYYY indica l’anno, mm indica il mese e dd indica il giorno.

Con il parametro run è possibile specificare la corsa di riferimento che deve essere espressa come un orario valido usando il seguente formato: HH:MM dove HH indica l’ora e MM indica i minuti. Gli orari delle corse sono sempre espressi come orario UTC.

Non è richiesta alcuna autenticazione per utilizzare queste API, a meno che la richiesta di scaricamento di pacchetti di open data non sia relativa a un set di dati ad accesso limitato previa autenticazione.

Come ottenere un token di accesso

Per utilizzare l’API autenticata, l’utente deve fornire un token di accesso. Il token viene ottenuto in risposta all’API di login.

• POST https://meteohub.agenziaitaliameteo.it/auth/login

Esempio del corpo della richiesta:

{ 
  "username": "user@example.com", 
  "password": "string", 
}

Come creare una richiesta di estrazione utilizzando le API

Per creare una richiesta di estrazione dei dati è necessario utilizzare la seguente API:

• POST https://meteohub.agenziaitaliameteo.it/api/data

Esempio del corpo della richiesta:

{ 
"request_name": name of the request, 
 "reftime": { 
   "from": "2022-01-10T11:04:54.615Z", 
   "to": "2022-01-10T11:04:54.615Z" 
  }, 
  "dataset_names": [ 
    list of datasets 
   ], 
   "filters": { 
      "area": [{}], 
      "level": [{}], 
      "origin": [ {}], 
      "proddef": [{} ], 
      "product": [{}], 
      "quantity": [{}], 
      "run": [{}], 
      "task": [{}], 
      "timerange": [ {}], 
       "network": [{}] 
     }, 
     "output_format": "json"/null, 
     "only_reliable": true/false, 
     "postprocessors": [ object ] //elenco dei postprocessori richiesti con la loro specifica configurazione
} 

Nel corpo della richiesta devono essere specificati i metadati relativi ai dati desiderati. I filtri sono specifici per la categoria del set di dati (vedere la tabella nel capitolo precedente “Scaricare dati dall’interfaccia web”).

Output_format e only_reliable sono parametri specifici per i dati delle osservazioni: il primo specifica se l’utente desidera che i dati di uscita siano in formato JSON anziché nel formato predefinito (BUFR). Il secondo specifica se l’utente desidera scaricare solo i dati convalidati

Per utilizzare questa API è necessaria un’autenticazione. Il token di accesso ottenuto dall’API di accesso deve essere incluso come autorizzazione nel request Header.

Come creare una richiesta pianificata di estrazione dei dati utilizzando le API

Per creare una richiesta pianificata è necessario utilizzare la seguente API:

• POST https://meteohub.agenziaitaliameteo.it/api/schedules

Il corpo della richiesta, dove sono specificati tutti i metadati relativi alla richiesta, è simile a quello descritto nel capitolo precedente “Come creare una richiesta di estrazione dati“. È necessario aggiungere i parametri per specificare l’intervallo di pianificazione.

I metodi di pianificazione disponibili sono:

1. Richiesta periodica: i dati vengono estratti a specifici intervalli di tempo:

"period-settings": { 
  "every": interval in number, 
  "every": interval in number, 
  "period": "hours”/"days"/”months”/”years” 
} 

2. Richiesta puntuale: i dati vengono estratti in giorni specifici in un momento specifico

"crontab-settings": { 
  "minute": number //  gamma tra
 0-59,     
  "hour": number  //  gamma tra
 0-23,     
  "day_of_week": number	//  gamma tra
 0-7 dove 0 e 7 si riferiscono a domenica, 1 a lunedì, e via di seguito
  "day_of_month": number  //  gamma tra
 0-31,     
  "month_of_year": number //  gamma tra
 1-12 dove 1 si riferisce a gennaio e 12 si riferisce a dicembre  
} 

3. Richiesta pronta per i dati: i dati vengono estratti non appena sono disponibili sulla piattaforma:

"on-data-ready": true,

Per utilizzare quetsa API è necessaria un’autenticazione. Il token di accesso ottenuto dall’API di accesso deve essere incluso come autorizzazione nel request Header.

Come scaricare i dati utilizzando le API

Per ottenere l’elenco di tutte le richieste inviate e il loro stato questa API deve essere utilizzata:

• GET https://meteohub.agenziaitaliameteo.it/api/requests

Se l’estrazione dei dati è stata completata, il parametro fileoutput nella risposta indica il nome del file di output.

Per scaricare i dati di output è necessario utilizzare la seguente API:

• GET https://meteohub.agenziaitaliameteo.it/api/data/{filename}

dove il parametro filename specifica il file da scaricare.

Per utilizzare questa API è necessaria un’autenticazione. Il token di accesso ottenuto dall’API di accesso deve essere incluso come autorizzazione nel request Header.