Documentazione dell'API meteo

Questa API dà accesso ai dati di previsione meteo per tutti i modelli. Puoi recuperare dati meteo storici e previsioni specificando parametri come intervallo temporale, coordinate e variabili di interesse.

Puoi usare il nostro client Python su GitHub oppure integrare direttamente gli endpoint con i dettagli qui sotto.

Se stai integrando GribStream con uno strumento di IA, inizia da GribStream per strumenti di IA.

Endpoint Timeseries

Per una coordinata, un parametro meteorologico e un intervallo temporale, possono esistere più valori previsti. Ogni valore corrisponde a un diverso orizzonte di previsione, cioè a un diverso lead time.

L'API restituisce, per ogni orario, il valore previsto con il lead time più breve. In pratica ricevi la previsione più recente disponibile in quel momento, spesso la più utile per analisi e applicazioni operative. Nei workflow di data science questa serie viene spesso chiamata previsione "best" (migliore disponibile) o serie "nowcast".

POST https://gribstream.com/api/v2/<model>/timeseries

Rinominato Prima era /history. Il vecchio percorso continua a funzionare.

Modelli disponibili

rap - Rapid Refresh (RAP)
gfs - Global Forecast System (GFS)
gdas - Global Data Assimilation System (GDAS)
nbm - National Blend of Models (NBM) (griglia principale CONUS)
nbmak - National Blend of Models (NBM) (griglia Alaska)
nbmhi - National Blend of Models (NBM) (griglia Hawaii)
nbmpr - National Blend of Models (NBM) (griglia Puerto Rico)
nbmgu - National Blend of Models (NBM) (griglia Guam)
nbmoc - National Blend of Models (NBM) (griglia oceanica)
nbmqmd - National Blend of Models QMD (CONUS)
nbmpar - National Blend of Models Parallel (griglia CONUS, NBM v5)
nbmparak - National Blend of Models Parallel (griglia Alaska, NBM v5)
nbmparhi - National Blend of Models Parallel (griglia Hawaii, NBM v5)
nbmparpr - National Blend of Models Parallel (griglia Puerto Rico, NBM v5)
nbmpargu - National Blend of Models Parallel (griglia Guam, NBM v5)
nbmparoc - National Blend of Models Parallel (griglia oceanica, NBM v5)
nbmparqmd - National Blend of Models Parallel QMD (CONUS, NBM v5)
aigfssfc - AI Global Forecast System Surface (AIGFS Surface)
aigfspres - AI Global Forecast System Pressure Levels (AIGFS Pressure)
aigefssfc - AI Global Ensemble Forecast System Surface (AIGEFS Surface)
aigefspres - AI Global Ensemble Forecast System Pressure Levels (AIGEFS Pressure)
dafsgtg - Domestic Aviation Forecast System Graphical Turbulence Guidance (CONUS)
dafsificonus - Domestic Aviation Forecast System In-Flight Icing (CONUS)
dafsifiak - Domestic Aviation Forecast System In-Flight Icing (Alaska)
cwawrf15 - Taiwan CWA WRF 15 km Regional Forecast
ccpa1hndgd25 - Climatologically Calibrated Precipitation Analysis (1-hour CONUS)
spctstm1hr - SPC HREF Thunderstorm Probability (1 hour)
spctstm4hr - SPC HREF Thunderstorm Probability (4 hour)
spcltg4hr - SPC HREF Lightning-density Probability (4 hour)
spchail4hr - SPC HREF Calibrated Hail Probability (4 hour)
spctor4hr - SPC HREF Calibrated Tornado Probability (4 hour)
spcwind4hr - SPC HREF Calibrated Severe Wind Probability (4 hour)
uvi - NOAA Ultraviolet Index Forecast
fourcastnetgfs - FourCastNet Global Forecast System (FourCastNetGFS)
urma - Unrestricted Mesoscale Analysis (URMA)
rtma - Real-Time Mesoscale Analysis API (RTMA)
hrrr - High-Resolution Rapid Refresh (HRRR)
rrfsprslev - Rapid Refresh Forecast System pressure levels (RRFS)
rrfs2dfld - Rapid Refresh Forecast System 2D fields (RRFS)
refsprslev - Rapid Refresh Forecast System Ensemble (RRFS Ens)
graphcast - GraphCast Global Forecast System (GFS GraphCast)
gefsatmosmean - Global Ensemble Forecast System (GEFS Atmos Mean)
gefsatmos - Global Ensemble Forecast System (GEFS Atmos)
gefschem - Global Ensemble Forecast System (GEFS Chem)
gefswaveprob - Global Ensemble Forecast System (GEFS Wave Prob)
cfsflxf - Climate Forecast System (CFS Radiative Fluxes)
cfspgbf - Climate Forecast System (CFS Pressure)
cfsipvf - Climate Forecast System (CFS Isentropic)
cfsocnf - Climate Forecast System (CFS Ocean)
cdas - Climate Data Assimilation System (CDAS1)
ifsoper - Integrated Forecasting System - Operational (IFS Oper)
ifswave - Integrated Forecasting System - Wave (IFS Wave)
ifsenfo - Integrated Forecasting System - Ensemble Forecast (IFS Enfo)
ifswaef - Integrated Forecasting System - Wave Ensemble Forecast (IFS Waef)
aifsoper - Artificial Intelligence Forecasting System (AIFS)
aifsenfo - Artificial Intelligence Forecasting System Ensemble (AIFS Ensemble)

Header della richiesta

Header	Valore	Nota
`Content-Type`	`application/json`	Valore default e unico valore valido.
`Accept`	Scegli uno: `text/csv` `application/json` `application/ndjson`	Seleziona il formato della risposta. Il default è `text/csv`
`Accept-Encoding`	`gzip`	Opzionale ma consigliato, per ricevere una risposta compressa
`Authorization`	`Bearer <token>`	Sostituisci <token> con il tuo token di autenticazione

Parametri del corpo della richiesta

Il corpo della richiesta (request body) deve essere un oggetto JSON con la seguente struttura:

Parametro	Tipo	Descrizione	Obbligatorio
`fromTime`	`string` (ISO 8601)	Orario di inizio del periodo di previsione.	Sì, usando `(fromTime, untilTime)` oppure `timesList`
`untilTime`	`string` (ISO 8601)	Orario di fine del periodo di previsione.	Sì, usando `(fromTime, untilTime)` oppure `timesList`
`timesList`	`array` di string (ISO 8601)	Lista esplicita degli orari di validità da restituire; ogni valore corrisponde a `forecasted_time`.	Sì, usando `(fromTime, untilTime)` oppure `timesList`
`asOf`	`string` (ISO 8601)	Timestamp di cutoff/riferimento: vengono considerati solo i run del modello generati in quel momento o prima.	No
`minLeadTime`	`string` (duration)	Lead time minimo, incluso. Stringa di durata come `"45m"` o `"18h"`. Ha precedenza su `minHorizon`/`maxHorizon`.	No
`maxLeadTime`	`string` (duration)	Lead time massimo, incluso. Stringa di durata come `"45m"` o `"18h"`. Ha precedenza su `minHorizon`/`maxHorizon`.	No
`minHorizon`	`integer`	Deprecato (usa `minLeadTime`). Lead time minimo in ore, incluso.	No
`maxHorizon`	`integer`	Deprecato (usa `maxLeadTime`). Lead time massimo in ore, incluso.	No
`coordinates`	`array` di `coordinate`	Lista di coordinate geografiche. Opzionale quando fornisci `grid`; puoi inviare entrambe.	Sì: devi fornire almeno uno tra `coordinates` e `grid`
`grid`	oggetto `grid`	Dominio rettangolare regolare. Il server restituisce ogni punto entro i limiti indicati, usando lo `step` spaziale richiesto. Può essere usato insieme a `coordinates`.	Sì: devi fornire almeno uno tra `coordinates` e `grid`
`variables`	`array` di `variable`	Lista di variabili meteorologiche da recuperare.	Sì
`expressions`	`array` di `expression`	Colonne calcolate sul server a partire dalle variabili richieste. Ogni voce viene restituita come colonna separata, usando l'alias fornito. Vedi la documentazione	No
`filter`	oggetto `filter`	Filtro booleano applicato dopo aver valutato tutte le `expressions`. Deve contenere un unico campo `expression` di tipo string. Le righe in cui l'espressione valuta a `false` vengono omesse dalla risposta.	No
`members`	`array` di integer	Per i modelli ensemble (`gefsatmos`, `ifsenfo`, `ifswaef` …) questo campo seleziona quali membri dell'ensemble includere nella risposta. Esempio: `"members": [2,3,4]`. Il default è `[0]`, cioè solo il membro `0`, la previsione di controllo.	No (solo modelli ensemble)

NOTA: l'orario selezionato deve essere specificato con l'intervallo (fromTime, untilTime) oppure con timesList

Oggetto Coordinate

Campo	Tipo	Descrizione	Obbligatorio
`lat`	`float`	Latitudine della coordinata.	Sì
`lon`	`float`	Longitudine della coordinata.	Sì
`name`	`string`	Nome opzionale per la coordinata, restituito nella risposta per identificare meglio la località.	No

Oggetto Grid

Campo	Tipo	Descrizione	Obbligatorio
`minLatitude`	number	Bordo meridionale (°N)	Sì
`maxLatitude`	number	Bordo settentrionale (°N)	Sì
`minLongitude`	number	Bordo occidentale (°E)	Sì
`maxLongitude`	number	Bordo orientale (°E)	Sì
`step`	number	Risoluzione in gradi decimali	Sì

Oggetto Variable

I campi name, level e info formano il selettore esatto della variabile meteorologica. Copia questi valori dal catalogo o dalla pagina del modello: sono identificatori API, non etichette da tradurre.

Consulta la lista completa dei parametri disponibili per ogni modello.

Campo	Tipo	Descrizione	Obbligatorio
`name`	`string`	Codice esatto del parametro meteorologico dal catalogo, per esempio `"TMP"` per la temperatura. Non tradurlo.	Sì
`level`	`string`	Livello atmosferico o di superficie esatto dal catalogo, per esempio `"2 m above ground"`.	Sì
`info`	`string`	Differenziatore esatto usato quando il modello ha più parametri con lo stesso `name` e `level`. Lascialo vuoto solo quando il valore nel catalogo è vuoto.	No
`alias`	`string`	Alias opzionale per la variabile. Se lo fornisci, questo alias viene usato come intestazione di colonna nella risposta.	No

Oggetto Expression

Campo	Tipo	Descrizione	Obbligatorio
`expression`	`string`	Crea colonne calcolate. Tutte le variabili selezionate sono accessibili tramite il loro alias. Vedi la documentazione	Sì
`alias`	`string`	Nome della colonna usato nella risposta per questo risultato calcolato.	Sì

Oggetto Filter

Campo	Tipo	Descrizione	Obbligatorio
`expression`	string	Espressione booleana nello stesso DSL usato da `expressions`. Può fare riferimento ad alias definiti in precedenza nel corpo della richiesta.	Sì

Richiesta di esempio

POST https://gribstream.com/api/v2/hrrr/timeseries
Content-Type: application/json
Accept-Encoding: gzip
Authorization: Bearer <token>
Payload:
{
    "fromTime": "2024-09-10T00:00:00Z",
    "untilTime": "2024-09-10T10:00:00Z",
    "asOf": "2024-09-10T05:00:00Z",
    "minLeadTime": "1h",
    "maxLeadTime": "48h",
    "coordinates": [{ "lat": 40.7306, "lon": -73.9352, "name": "New York City" }],
    "variables": [
        { "name": "UGRD", "level": "1000 mb", "alias": "uwind" },
        { "name": "VGRD", "level": "1000 mb", "alias": "vwind" }
    ],
    "expressions": [
        { "expression": "func.Hypot(uwind, vwind)", "alias": "wind_magnitude" },
        { "expression": "int(270 - func.Atan2(vwind, uwind) * 180 / 3.14159) % 360", "alias": "wind_direction" }
    ]
}

Risposta di esempio

Il formato della risposta è determinato dall'header Accept. L'API supporta tre formati di risposta:

Accept: text/csv - la risposta è un file CSV con i dati di previsione.
Accept: application/json - la risposta è un singolo array JSON di oggetti.
Accept: application/ndjson - la risposta è JSON delimitato da newline, con un oggetto JSON per riga.

Se includi l'header Accept-Encoding: gzip, la risposta viene compressa con gzip.

NOTA: la risposta non è strettamente ordinata.

Esempio di risposta CSV

forecasted_at,forecasted_time,lat,lon,name,uwind,vwind,wind_direction,wind_magnitude
2024-09-10T02:00:00Z,2024-09-10T03:00:00Z,40.7306,-73.9352,New York City,7.1213,1.7680,256,7.3375
2024-09-10T05:00:00Z,2024-09-10T08:00:00Z,40.7306,-73.9352,New York City,5.2585,-1.1512,282,5.3831
2024-09-10T01:00:00Z,2024-09-10T02:00:00Z,40.7306,-73.9352,New York City,8.1815,1.6363,258,8.3435
2024-09-10T05:00:00Z,2024-09-10T07:00:00Z,40.7306,-73.9352,New York City,6.9156,-1.4414,281,7.0642
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,40.7306,-73.9352,New York City,8.0572,2.9389,249,8.5765
2024-09-10T03:00:00Z,2024-09-10T04:00:00Z,40.7306,-73.9352,New York City,6.4841,2.5385,248,6.9633
2024-09-10T05:00:00Z,2024-09-10T06:00:00Z,40.7306,-73.9352,New York City,6.8368,0.1001,269,6.8375
2024-09-10T04:00:00Z,2024-09-10T05:00:00Z,40.7306,-73.9352,New York City,6.4087,3.0921,244,7.1157
2024-09-09T23:00:00Z,2024-09-10T00:00:00Z,40.7306,-73.9352,New York City,6.1795,3.9539,237,7.3362
2024-09-10T05:00:00Z,2024-09-10T09:00:00Z,40.7306,-73.9352,New York City,4.7715,-0.5644,276,4.8047

Esempio di risposta JSON (array JSON)

[{"forecasted_at":"2024-09-10T02:00:00Z","forecasted_time":"2024-09-10T03:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.121286392211914,"vwind":1.7680130004882812,"wind_direction":256,"wind_magnitude":7.337478439477567}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T01:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.057228088378906,"vwind":2.938892364501953,"wind_direction":249,"wind_magnitude":8.576480210336284}
,{"forecasted_at":"2024-09-10T01:00:00Z","forecasted_time":"2024-09-10T02:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.181510925292969,"vwind":1.6362571716308594,"wind_direction":258,"wind_magnitude":8.34352794400556}
,{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T06:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.836750030517578,"vwind":0.10012435913085938,"wind_direction":269,"wind_magnitude":6.837483152964509}
,{"forecasted_at":"2024-09-09T23:00:00Z","forecasted_time":"2024-09-10T00:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.179473876953125,"vwind":3.953920364379883,"wind_direction":237,"wind_magnitude":7.33616954846356}
,{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T07:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.915561676025391,"vwind":-1.4414329528808594,"wind_direction":281,"wind_magnitude":7.064185887458082}
,{"forecasted_at":"2024-09-10T03:00:00Z","forecasted_time":"2024-09-10T04:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.484088897705078,"vwind":2.538473129272461,"wind_direction":248,"wind_magnitude":6.963279016482147}
,{"forecasted_at":"2024-09-10T04:00:00Z","forecasted_time":"2024-09-10T05:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.408748626708984,"vwind":3.0920562744140625,"wind_direction":244,"wind_magnitude":7.115677828885149}
,{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T08:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":5.258523941040039,"vwind":-1.1512451171875,"wind_direction":282,"wind_magnitude":5.383069696589422}
,{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":4.771465301513672,"vwind":-0.564422607421875,"wind_direction":276,"wind_magnitude":4.804732459078015}
]

Esempio di risposta NDJSON (delimitata per righe)

{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T07:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.915561676025391,"vwind":-1.4414329528808594,"wind_direction":281,"wind_magnitude":7.064185887458082}
{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T08:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":5.258523941040039,"vwind":-1.1512451171875,"wind_direction":282,"wind_magnitude":5.383069696589422}
{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":4.771465301513672,"vwind":-0.564422607421875,"wind_direction":276,"wind_magnitude":4.804732459078015}
{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T06:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.836750030517578,"vwind":0.10012435913085938,"wind_direction":269,"wind_magnitude":6.837483152964509}
{"forecasted_at":"2024-09-10T03:00:00Z","forecasted_time":"2024-09-10T04:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.484088897705078,"vwind":2.538473129272461,"wind_direction":248,"wind_magnitude":6.963279016482147}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T01:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.057228088378906,"vwind":2.938892364501953,"wind_direction":249,"wind_magnitude":8.576480210336284}
{"forecasted_at":"2024-09-09T23:00:00Z","forecasted_time":"2024-09-10T00:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.179473876953125,"vwind":3.953920364379883,"wind_direction":237,"wind_magnitude":7.33616954846356}
{"forecasted_at":"2024-09-10T01:00:00Z","forecasted_time":"2024-09-10T02:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.181510925292969,"vwind":1.6362571716308594,"wind_direction":258,"wind_magnitude":8.34352794400556}
{"forecasted_at":"2024-09-10T04:00:00Z","forecasted_time":"2024-09-10T05:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.408748626708984,"vwind":3.0920562744140625,"wind_direction":244,"wind_magnitude":7.115677828885149}
{"forecasted_at":"2024-09-10T02:00:00Z","forecasted_time":"2024-09-10T03:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.121286392211914,"vwind":1.7680130004882812,"wind_direction":256,"wind_magnitude":7.337478439477567}

Campi della risposta:

Campo	Descrizione
`forecasted_at`	Orario del run del modello: quando la previsione è stata generata o emessa.
`forecasted_time`	Orario di validità: l'orario a cui si applica la previsione.
`lat`	Latitudine della coordinata.
`lon`	Longitudine della coordinata.
`name`	Nome fornito nella richiesta per il set di coordinate.
`uwind` `vwind` `wind_direction` `wind_magnitude`	Una colonna per ogni variabile o espressione derivata. Per default, le variabili usano `[name]\|[level]\|[info]`.

Note d'uso

Tutti gli orari devono essere in formato ISO 8601, per esempio "2022-08-10T00:00:00Z".
Usa minLeadTime/maxLeadTime (preferiti) oppure i parametri deprecati minHorizon/maxHorizon (ore) per limitare i lead time.
Devi specificare almeno una località (coordinates e/o grid) e una variabile.
Il parametro asOf è un timestamp di cutoff per richieste time-travel. L'API considera solo i run del modello generati in quel momento o prima, così backtest e simulazioni non usano per errore previsioni emesse più tardi. Se non lo fornisci, viene usata la previsione più recente disponibile.

Autenticazione

Devi includere un token di autenticazione valido nell'header Authorization. Per ottenere un token,

Includi il token negli header della richiesta in questo modo:

Authorization: Bearer <token>

Comando cURL di esempio

curl -X POST 'https://gribstream.com/api/v2/hrrr/timeseries' \
        -H "Content-Type: application/json" \
        -H "Accept-Encoding: gzip" \
        -H "Authorization: Bearer [API_TOKEN]" \
        -d '{
            "fromTime": "2024-09-10T00:00:00Z",
            "untilTime": "2024-09-10T10:00:00Z",
            "asOf": "2024-09-10T05:00:00Z",
            "minLeadTime": "1h",
            "maxLeadTime": "48h",
            "coordinates": [{ "lat": 40.7306, "lon": -73.9352, "name": "New York City" }],
            "variables": [
              { "name": "UGRD", "level": "1000 mb", "alias": "uwind" },
              { "name": "VGRD", "level": "1000 mb", "alias": "vwind" }
            ],
            "expressions": [
              { "expression": "func.Hypot(uwind, vwind)", "alias": "wind_magnitude" },
              { "expression": "int(270 - func.Atan2(vwind, uwind) * 180 / 3.14159) % 360", "alias": "wind_direction" }
            ]
        }' | gunzip | head -20

Questo comando recupera i dati di previsione e stampa le prime 20 righe della risposta decompressa.

Gestione degli errori

Se la richiesta contiene un errore, l'API restituisce un messaggio di errore con il codice di stato HTTP appropriato.

Codici di errore comuni

Codice di stato	Significato	Descrizione
400 Bad Request	Parametri della richiesta non validi.	Succede quando mancano parametri obbligatori o quando i valori non sono validi.
401 Unauthorized	Autenticazione non riuscita.	Succede quando il token di autenticazione manca o non è valido.
429 Too Many Requests	Quota esaurita.	Succede quando esaurisci la quota. La risposta include un header `Retry-After` con il tempo di attesa prima di riprovare.
500 Internal Server Error	Errore del server.	Succede quando si verifica un errore durante l'elaborazione della richiesta sul server.

Endpoint Runs

Recupera tutti i run di previsione in un intervallo temporale, per una lista di coordinate e una lista di parametri meteorologici. Puoi anche filtrare per una finestra di lead time con minLeadTime e maxLeadTime.

POST https://gribstream.com/api/v2/<model>/runs

Rinominato Prima era /forecasts. Il vecchio percorso continua a funzionare.