Documentazione API per dati meteo storici e previsioni

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 eleggibile più breve. In pratica ricevi il run del modello più recente consentito dai filtri della richiesta, spesso il più utile per analisi e applicazioni operative. Nei workflow di data science questa serie viene spesso chiamata previsione "best" (migliore idonea) o serie "nowcast".

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

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

Modelli e dataset disponibili

Consulta il catalogo dei modelli per vedere la lista aggiornata dei dataset supportati, con codici API esatti, parametri, livelli e copertura. Usa il codice del dataset nel segmento <model> del percorso indicato sopra.

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)	Cutoff sull'orario del run del modello: vengono considerati solo i run 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`
`includeMetadata`	`string[]`	Array facoltativo per timeseries e runs. native_coordinate aggiunge native_lat e native_lon; index_updated_at aggiunge index_updated_at. Puoi richiedere entrambi, senza crediti aggiuntivi per variabili meteo.	No
`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
`native_lat`, `native_lon`	lat e lon mantengono la posizione richiesta. native_lat e native_lon identificano il centro della cella selezionata, ripetuto in ogni riga di quella posizione. Le longitudini native seguono la convenzione della griglia: 286° e −74° indicano la stessa longitudine.
`index_updated_at`	Ultimo aggiornamento della riga dell’indice, in UTC ISO 8601. Incluso quando viene richiesto index_updated_at.
`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 quattro 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.
Accept: application/vnd.apache.parquet - la risposta è un file Parquet tipizzato e compresso con ZSTD. Sono accettati anche gli alias application/x-parquet e application/parquet.

Parquet è un formato binario, quindi salvalo in un file invece di stamparlo nel terminale. Le colonne dinamiche mantengono i propri tipi e ammettono valori nulli; le colonne timestamp contengono valori UTC senza informazioni sul fuso orario e con risoluzione al secondo.

Per un risultato di grandi dimensioni, aggiungi ?delivery=url&format=csv, json, ndjson o parquet e invia Accept: application/json. Il corpo della richiesta non cambia e l’API restituisce i metadati del file insieme a un URL di download firmato e di breve durata. Senza questi parametri, tutti i formati mantengono la normale risposta inline.

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.
`native_lat`, `native_lon`	lat e lon mantengono la posizione richiesta. native_lat e native_lon identificano il centro della cella selezionata, ripetuto in ogni riga di quella posizione. Le longitudini native seguono la convenzione della griglia: 286° e −74° indicano la stessa longitudine.
`index_updated_at`	Ultimo aggiornamento della riga dell’indice, in UTC ISO 8601. Incluso quando viene richiesto index_updated_at.
`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 cutoff sull'orario del run del modello per richieste retrospettive. L'API considera solo i run del modello generati in quel momento o prima. Non dimostra che i dati selezionati fossero già disponibili in GribStream a quell'orario reale. 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.

Modelli e dataset disponibili

Consulta il catalogo dei modelli per vedere la lista aggiornata dei dataset supportati, con codici API esatti, parametri, livelli e copertura. Usa il codice del dataset nel segmento <model> del percorso indicato sopra.

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
`forecastedFrom`	`string` (ISO 8601)	Primo orario del run di previsione da includere.	Sì, usando `(forecastedFrom, forecastedUntil)` oppure `timesList`
`forecastedUntil`	`string` (ISO 8601)	Ultimo orario del run di previsione da includere.	Sì, usando `(forecastedFrom, forecastedUntil)` oppure `timesList`
`timesList`	`array` di string (ISO 8601)	Lista esplicita degli orari dei run del modello; ogni valore corrisponde a `forecasted_at`.	Sì, usando `(forecastedFrom, forecastedUntil)` oppure `timesList`
`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.	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`
`includeMetadata`	`string[]`	Array facoltativo per timeseries e runs. native_coordinate aggiunge native_lat e native_lon; index_updated_at aggiunge index_updated_at. Puoi richiedere entrambi, senza crediti aggiuntivi per variabili meteo.	No
`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 (forecastedFrom, forecastedUntil) oppure con timesList

Oggetto Coordinate

Campo	Tipo	Descrizione	Obbligatorio
`native_lat`, `native_lon`	lat e lon mantengono la posizione richiesta. native_lat e native_lon identificano il centro della cella selezionata, ripetuto in ogni riga di quella posizione. Le longitudini native seguono la convenzione della griglia: 286° e −74° indicano la stessa longitudine.
`index_updated_at`	Ultimo aggiornamento della riga dell’indice, in UTC ISO 8601. Incluso quando viene richiesto index_updated_at.
`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.

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/runs
Content-Type: application/json
Accept-Encoding: gzip
Authorization: Bearer <token>
Payload:
{
    "forecastedFrom": "2024-09-10T00:00:00Z",
    "forecastedUntil": "2024-09-10T00: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 quattro 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.
Accept: application/vnd.apache.parquet - la risposta è un file Parquet tipizzato e compresso con ZSTD. Sono accettati anche gli alias application/x-parquet e application/parquet.

Parquet è un formato binario, quindi salvalo in un file invece di stamparlo nel terminale. Le colonne dinamiche mantengono i propri tipi e ammettono valori nulli; le colonne timestamp contengono valori UTC senza informazioni sul fuso orario e con risoluzione al secondo.

Per un risultato di grandi dimensioni, aggiungi ?delivery=url&format=csv, json, ndjson o parquet e invia Accept: application/json. Il corpo della richiesta non cambia e l’API restituisce i metadati del file insieme a un URL di download firmato e di breve durata. Senza questi parametri, tutti i formati mantengono la normale risposta inline.

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-10T00:00:00Z,2024-09-10T01:00:00Z,40.7306,-73.9352,New York City,8.0572,2.9389,249,8.5765
2024-09-10T00:00:00Z,2024-09-11T02:00:00Z,40.7306,-73.9352,New York City,2.3471,-5.2970,336,5.7937
2024-09-10T00:00:00Z,2024-09-10T03:00:00Z,40.7306,-73.9352,New York City,7.2268,1.7030,256,7.4247
2024-09-10T00:00:00Z,2024-09-11T06:00:00Z,40.7306,-73.9352,New York City,-2.9925,-5.0025,30,5.8292
2024-09-10T00:00:00Z,2024-09-11T07:00:00Z,40.7306,-73.9352,New York City,-2.9643,-4.9196,31,5.7437
2024-09-10T00:00:00Z,2024-09-10T12:00:00Z,40.7306,-73.9352,New York City,4.7834,-4.3696,312,6.4787
2024-09-10T00:00:00Z,2024-09-10T10:00:00Z,40.7306,-73.9352,New York City,7.2718,0.5647,265,7.2937
2024-09-10T00:00:00Z,2024-09-11T10:00:00Z,40.7306,-73.9352,New York City,-2.9361,-4.5728,32,5.4343
2024-09-10T00:00:00Z,2024-09-11T05:00:00Z,40.7306,-73.9352,New York City,-3.1221,-5.8816,27,6.6589
2024-09-10T00:00:00Z,2024-09-10T06:00:00Z,40.7306,-73.9352,New York City,6.6521,1.6799,255,6.8610
2024-09-10T00:00:00Z,2024-09-11T00:00:00Z,40.7306,-73.9352,New York City,3.2101,-3.3758,316,4.6584
2024-09-10T00:00:00Z,2024-09-10T11:00:00Z,40.7306,-73.9352,New York City,6.9390,-2.4367,289,7.3544
...

Esempio di risposta JSON (array JSON)

[{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.078826904296875,"vwind":2.4223251342773438,"wind_direction":251,"wind_magnitude":7.481807896300802}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T07:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.181903839111328,"vwind":2.596050262451172,"wind_direction":247,"wind_magnitude":6.704879718622265}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-11T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":-2.627544403076172,"vwind":-5.187816619873047,"wind_direction":26,"wind_magnitude":5.815275648803582}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T08:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.091346740722656,"vwind":2.6632766723632812,"wind_direction":249,"wind_magnitude":7.5749746686515245}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T04:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.889509201049805,"vwind":2.7773094177246094,"wind_direction":248,"wind_magnitude":7.428242364996697}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T03:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.226800918579102,"vwind":1.7029743194580078,"wind_direction":256,"wind_magnitude":7.424740604863526}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T10:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.271799087524414,"vwind":0.5646705627441406,"wind_direction":265,"wind_magnitude":7.2936900683913555}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T12:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":4.783409118652344,"vwind":-4.369564056396484,"wind_direction":312,"wind_magnitude":6.4787416092446914}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T05:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.676166534423828,"vwind":2.414224624633789,"wind_direction":252,"wind_magnitude":8.046863563053401}
,{"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}
...
]

Esempio di risposta NDJSON (delimitata per righe)

{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T03:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.226800918579102,"vwind":1.7029743194580078,"wind_direction":256,"wind_magnitude":7.424740604863526}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T17:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":2.3053665161132812,"vwind":-3.231029510498047,"wind_direction":324,"wind_magnitude":3.969164455061737}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T19:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":1.7580318450927734,"vwind":-2.8487396240234375,"wind_direction":328,"wind_magnitude":3.3475354238366912}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T16:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":2.373655319213867,"vwind":-3.552021026611328,"wind_direction":326,"wind_magnitude":4.272129790622153}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T20:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":1.9354515075683594,"vwind":-2.271472930908203,"wind_direction":319,"wind_magnitude":2.9842187945922025}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T02:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.008834838867188,"vwind":1.1038799285888672,"wind_direction":262,"wind_magnitude":8.084552329782657}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T12:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":4.783409118652344,"vwind":-4.369564056396484,"wind_direction":312,"wind_magnitude":6.4787416092446914}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T04:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.889509201049805,"vwind":2.7773094177246094,"wind_direction":248,"wind_magnitude":7.428242364996697}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T13:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":2.683929443359375,"vwind":-4.015068054199219,"wind_direction":326,"wind_magnitude":4.829518478770162}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T18:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":1.8502693176269531,"vwind":-3.0554637908935547,"wind_direction":328,"wind_magnitude":3.5720240096076235}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-11T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":-2.627544403076172,"vwind":-5.187816619873047,"wind_direction":26,"wind_magnitude":5.815275648803582}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T14:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":1.9734878540039062,"vwind":-4.105434417724609,"wind_direction":334,"wind_magnitude":4.555134034047598}
...

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.
`native_lat`, `native_lon`	lat e lon mantengono la posizione richiesta. native_lat e native_lon identificano il centro della cella selezionata, ripetuto in ogni riga di quella posizione. Le longitudini native seguono la convenzione della griglia: 286° e −74° indicano la stessa longitudine.
`index_updated_at`	Ultimo aggiornamento della riga dell’indice, in UTC ISO 8601. Incluso quando viene richiesto index_updated_at.
`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.

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/runs' \
-H "Content-Type: application/json" \
-H "Accept-Encoding: gzip" \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "forecastedFrom": "2024-09-10T00:00:00Z",
    "forecastedUntil": "2024-09-10T00: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.

Coordinate della griglia nativa

Restituisce tutte le coppie latitudine/longitudine native in un riquadro inclusivo. Fornisci i quattro limiti; minLat non deve superare maxLat. Longitudini: −180..180 o 0..360; limiti decrescenti attraversano il bordo. Nessuna paginazione. Copia lat/lon in coordinates della richiesta meteo.

GET https://gribstream.com/api/v2/<dataset>/native-coordinates

Header della richiesta

Header	Valore	Commento
`Accept`	`text/csv application/json application/ndjson application/vnd.apache.parquet`	Seleziona il formato; usa CSV se omesso o non supportato.
`Accept-Encoding`	`gzip`	Facoltativo; richiede una risposta compressa.
`Authorization`	`Bearer <token>`	È richiesto un token API registrato.

Parametri della query

Parametro	Tipo	Descrizione	Obbligatorio
`minLat`	`number`	Limite sud di latitudine (inclusivo). `-90..90`	Sì
`maxLat`	`number`	Limite nord di latitudine (inclusivo). `-90..90`	Sì
`minLon`	`number`	Limite ovest di longitudine (inclusivo). `-180..360`	Sì
`maxLon`	`number`	Limite est di longitudine (inclusivo). `-180..360`	Sì

Richiesta di esempio

curl --get 'https://gribstream.com/api/v2/gfs/native-coordinates' \
  -H 'Authorization: Bearer [API_TOKEN]' \
  -H 'Accept: application/json' \
  --data-urlencode 'minLat=40.7' \
  --data-urlencode 'maxLat=40.8' \
  --data-urlencode 'minLon=-74.1' \
  --data-urlencode 'maxLon=-73.9'

Risposte di esempio

CSV è il predefinito. Usa Accept: application/json per un array, application/ndjson (o application/x-ndjson) per JSON Lines o application/vnd.apache.parquet per Parquet. Tutti contengono solo lat e lon. Le specifiche della griglia sono nei dettagli gratuiti del catalogo. delivery=url è disponibile solo per query meteo.

Risposta CSV di esempio

lat,lon
40.75,286

Risposta JSON di esempio

[
  {"lat": 40.75, "lon": 286}
]

Risposta JSON Lines di esempio

{"lat":40.75,"lon":286}

Risposta Parquet di esempio

Parquet è binario. Salvalo in un file; le uniche colonne sono lat (DOUBLE) e lon (DOUBLE), con una coppia di coordinate per riga.

curl --get 'https://gribstream.com/api/v2/gfs/native-coordinates' \
  -H 'Authorization: Bearer [API_TOKEN]' \
  -H 'Accept: application/vnd.apache.parquet' \
  --data-urlencode 'minLat=40.7' \
  --data-urlencode 'maxLat=40.8' \
  --data-urlencode 'minLon=-74.1' \
  --data-urlencode 'maxLon=-73.9' \
  --output native-coordinates.parquet

Campi della risposta

Campo	Descrizione
`lat, lon`	Latitudine e longitudine del centro della cella nativa.

Note d’uso

Le longitudini native seguono la convenzione della griglia: 286° e −74° indicano la stessa longitudine.

Serve un token registrato. Ogni richiesta costa un credito per 500 coordinate restituite, arrotondato per eccesso: come un parametro meteo per una data. Riquadri vuoti costano zero. Nessuna quota gratuita. Senza quota: 429 e Retry-After.

Il flusso può fermarsi alla quota, con al massimo un credito aggiuntivo (500 coordinate) per richiesta ammessa. La risposta resta valida con HTTP 200: CSV e JSON Lines terminano all’ultima riga, JSON chiude l’array e Parquet finalizza il file. Non si aggiungono statistiche né indicazioni di completezza.

Le immagini satellitari includono pixel che guardano oltre la Terra. Vengono restituiti solo quelli con una posizione geografica. Le coordinate descrivono centri di celle, non disponibilità di valori meteo. AICON ha un errore di quantizzazione inferiore a 0,5 m.

Codici di errore

Stato	Descrizione
`400 Bad Request`	Riquadro mancante o non valido, o campi di paginazione non supportati.
`401 Unauthorized`	Token mancante o non valido.
`403 Forbidden`	Gli inventari richiedono un token registrato.
`404 Not Found`	Dataset sconosciuto.
`429 Too Many Requests`	Quota esaurita; rispetta Retry-After.
`501 Not Implemented`	Geometria nativa non supportata.
`503 Service Unavailable`	Fonte delle coordinate temporaneamente non disponibile.

Riferimento API del catalogo · OpenAPI

Documentazione dell'API meteo

Endpoint Timeseries

Modelli e dataset disponibili

Header della richiesta

Parametri del corpo della richiesta

Oggetto Coordinate

Oggetto Grid

Oggetto Variable

Oggetto Expression

Oggetto Filter

Richiesta di esempio

Risposta di esempio

Esempio di risposta CSV

Esempio di risposta JSON (array JSON)

Esempio di risposta NDJSON (delimitata per righe)

Note d'uso

Autenticazione

Comando cURL di esempio

Gestione degli errori

Codici di errore comuni

Endpoint Runs

Modelli e dataset disponibili

Header della richiesta

Parametri del corpo della richiesta

Oggetto Coordinate

Oggetto Grid

Oggetto Variable

Oggetto Expression

Oggetto Filter

Richiesta di esempio

Risposta di esempio

Esempio di risposta CSV

Esempio di risposta JSON (array JSON)

Esempio di risposta NDJSON (delimitata per righe)

Note d'uso

Autenticazione

Comando cURL di esempio

Gestione degli errori

Codici di errore comuni

Coordinate della griglia nativa

Header della richiesta

Parametri della query

Richiesta di esempio

Risposte di esempio

Risposta CSV di esempio

Risposta JSON di esempio

Risposta JSON Lines di esempio

Risposta Parquet di esempio

Campi della risposta

Note d’uso

Codici di errore

Contatti