GribStream

Guida rapida

Accedi, crea un token API (c'è anche un piano gratuito) e fai la prima richiesta API. Puoi copiare e incollare gli esempi qui sotto (cURL / Python), cambiare token e timestamp, e iniziare subito. Sostituisci [API_TOKEN] con il tuo token, senza le parentesi quadre.

1. Eseguire una richiesta semplice

Interroga la temperatura oraria del 1 maggio 2025 a Times Square secondo il Global Forecast System (GFS) di NOAA.

URL:

Useremo questo endpoint:

POST https://gribstream.com/api/v2/[MODEL]/timeseries

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

Sostituisci [MODEL] con il codice di GFS, cioè gfs, ottenendo:

POST https://gribstream.com/api/v2/gfs/timeseries

Puoi vedere tutti i modelli disponibili qui.

Payload:

I timestamp sono in formato UTC ISO 8601. Qui chiediamo un intervallo temporale da fromTime a untilTime.

Le coordinate sono coppie numeriche (latitude, longitude).

I parametri meteorologici si selezionano con tuple (name, level, info). Sono selettori esatti del catalogo: name è il codice del parametro nella fonte, level è il livello verticale o di superficie, e info distingue varianti quando serve. Guardando GFS, vedrai che la temperatura è disponibile con TMP a molti livelli. In questo esempio useremo 2 m above ground.

Codice:

curl -X POST 'https://gribstream.com/api/v2/gfs/timeseries' \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "fromTime": "2025-05-01T00:00:00Z",
    "untilTime": "2025-05-02T00:00:00Z",
    "coordinates": [{ "lat": 40.758, "lon": -73.985 }],
    "variables": [{ "name": "TMP", "level": "2 m above ground", "info": "" }]
}'

import requests

API_TOKEN = "[API_TOKEN]"  # Replace with your token

payload = {
    "fromTime": "2025-05-01T00:00:00Z",
    "untilTime": "2025-05-02T00:00:00Z",
    "coordinates": [
        { "lat": 40.758, "lon": -73.985 }
    ],
    "variables": [
        { "name": "TMP", "level": "2 m above ground", "info": "" }
    ]
}

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
}

response = requests.post("https://gribstream.com/api/v2/gfs/timeseries", json=payload, headers=headers)
response.raise_for_status()

print(response.text)

Risultato:

forecasted_at,forecasted_time,lat,lon,name,TMP|2 m above ground|
2025-05-01T06:00:00Z,2025-05-01T09:00:00Z,40.7580,-73.9850,,286.7000
2025-05-01T06:00:00Z,2025-05-01T11:00:00Z,40.7580,-73.9850,,286.5539
2025-05-01T00:00:00Z,2025-05-01T01:00:00Z,40.7580,-73.9850,,292.2532
2025-05-01T12:00:00Z,2025-05-01T15:00:00Z,40.7580,-73.9850,,292.2911
2025-05-01T18:00:00Z,2025-05-01T19:00:00Z,40.7580,-73.9850,,292.7923
2025-05-01T12:00:00Z,2025-05-01T14:00:00Z,40.7580,-73.9850,,290.9911
2025-05-01T12:00:00Z,2025-05-01T17:00:00Z,40.7580,-73.9850,,293.8677
2025-05-01T12:00:00Z,2025-05-01T16:00:00Z,40.7580,-73.9850,,293.2000
2025-05-01T18:00:00Z,2025-05-01T20:00:00Z,40.7580,-73.9850,,292.3354
2025-05-01T18:00:00Z,2025-05-01T18:00:00Z,40.7580,-73.9850,,293.5384
2025-05-01T06:00:00Z,2025-05-01T08:00:00Z,40.7580,-73.9850,,287.1673
2025-05-01T12:00:00Z,2025-05-01T13:00:00Z,40.7580,-73.9850,,289.4673
2025-05-01T00:00:00Z,2025-05-01T04:00:00Z,40.7580,-73.9850,,289.4754
2025-05-01T00:00:00Z,2025-05-01T03:00:00Z,40.7580,-73.9850,,290.4711
2025-05-01T00:00:00Z,2025-05-01T05:00:00Z,40.7580,-73.9850,,288.8000
2025-05-01T00:00:00Z,2025-05-01T00:00:00Z,40.7580,-73.9850,,292.9684
2025-05-01T12:00:00Z,2025-05-01T12:00:00Z,40.7580,-73.9850,,287.7405
2025-05-01T00:00:00Z,2025-05-01T02:00:00Z,40.7580,-73.9850,,291.3480
2025-05-01T06:00:00Z,2025-05-01T06:00:00Z,40.7580,-73.9850,,288.2327
2025-05-01T06:00:00Z,2025-05-01T10:00:00Z,40.7580,-73.9850,,286.2595
2025-05-01T18:00:00Z,2025-05-01T22:00:00Z,40.7580,-73.9850,,290.9539
2025-05-01T06:00:00Z,2025-05-01T07:00:00Z,40.7580,-73.9850,,287.7000
2025-05-01T18:00:00Z,2025-05-01T23:00:00Z,40.7580,-73.9850,,290.0113
2025-05-01T18:00:00Z,2025-05-01T21:00:00Z,40.7580,-73.9850,,291.8027

Nota che le righe non sono ordinate né per forecasted_at né per forecasted_time. È una scelta di efficienza dell'API.

2. Nomi delle località e alias delle variabili

Quando leggi la risposta, spesso è comodo usare un nome invece della coppia di coordinate. Puoi dare alla località un nome leggibile o salvare un ID. È utile per creare visualizzazioni e dashboard senza una fase di pre-elaborazione. Basta aggiungere la proprietà name a ogni coordinata. Qui useremo TimesSquare.

Allo stesso modo, la convenzione a tre parti per le variabili meteorologiche può essere poco leggibile (TMP|2 m above ground|), quindi puoi rinominare la variabile con una proprietà extra chiamata alias. È utile se vuoi cambiare programmaticamente temperatura a diversi livelli, ma continuare a chiamare la colonna temp. Pensalo come la clausola AS in SQL.

Codice:

curl -X POST 'https://gribstream.com/api/v2/gfs/timeseries' \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "fromTime": "2025-05-01T00:00:00Z",
    "untilTime": "2025-05-02T00:00:00Z",
    "coordinates": [{ "lat": 40.758, "lon": -73.985 , "name": "TimesSquare"}],
    "variables": [{ "name": "TMP", "level": "2 m above ground", "info": "", "alias": "temp" }]
}'
import requests

API_TOKEN = "[API_TOKEN]"  # Replace with your token

payload = {
    "fromTime": "2025-05-01T00:00:00Z",
    "untilTime": "2025-05-02T00:00:00Z",
    "coordinates": [
        { "lat": 40.758, "lon": -73.985, "name": "TimesSquare" }
    ],
    "variables": [
        { "name": "TMP", "level": "2 m above ground", "info": "", "alias": "temp" }
    ]
}

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
}

response = requests.post("https://gribstream.com/api/v2/gfs/timeseries", json=payload, headers=headers)
response.raise_for_status()

print(response.text)

Risultato:

forecasted_at,forecasted_time,lat,lon,name,temp
2025-05-01T05:00:00Z,2025-05-01T06:00:00Z,40.7580,-73.9850,TimesSquare,287.7400
2025-05-01T10:00:00Z,2025-05-01T11:00:00Z,40.7580,-73.9850,TimesSquare,285.7200
2025-05-01T03:00:00Z,2025-05-01T04:00:00Z,40.7580,-73.9850,TimesSquare,289.1600
2025-05-01T08:00:00Z,2025-05-01T09:00:00Z,40.7580,-73.9850,TimesSquare,285.7200
2025-05-01T20:00:00Z,2025-05-01T21:00:00Z,40.7580,-73.9850,TimesSquare,291.7000
2025-05-01T04:00:00Z,2025-05-01T05:00:00Z,40.7580,-73.9850,TimesSquare,288.4300
2025-05-01T02:00:00Z,2025-05-01T03:00:00Z,40.7580,-73.9850,TimesSquare,290.1200
2025-05-01T09:00:00Z,2025-05-01T10:00:00Z,40.7580,-73.9850,TimesSquare,285.4300
2025-05-01T06:00:00Z,2025-05-01T07:00:00Z,40.7580,-73.9850,TimesSquare,286.8900
2025-05-01T19:00:00Z,2025-05-01T20:00:00Z,40.7580,-73.9850,TimesSquare,292.5500
2025-05-01T07:00:00Z,2025-05-01T08:00:00Z,40.7580,-73.9850,TimesSquare,286.3500
2025-05-01T15:00:00Z,2025-05-01T16:00:00Z,40.7580,-73.9850,TimesSquare,292.9300
2025-05-01T11:00:00Z,2025-05-01T12:00:00Z,40.7580,-73.9850,TimesSquare,286.8000
2025-05-01T18:00:00Z,2025-05-01T19:00:00Z,40.7580,-73.9850,TimesSquare,293.4100
2025-05-01T17:00:00Z,2025-05-01T18:00:00Z,40.7580,-73.9850,TimesSquare,293.8500
2025-05-01T12:00:00Z,2025-05-01T13:00:00Z,40.7580,-73.9850,TimesSquare,288.1300
2025-05-01T21:00:00Z,2025-05-01T22:00:00Z,40.7580,-73.9850,TimesSquare,291.0500
2025-05-01T13:00:00Z,2025-05-01T14:00:00Z,40.7580,-73.9850,TimesSquare,290.2100
2025-05-01T14:00:00Z,2025-05-01T15:00:00Z,40.7580,-73.9850,TimesSquare,291.3900
2025-05-01T01:00:00Z,2025-05-01T02:00:00Z,40.7580,-73.9850,TimesSquare,291.2300
2025-05-01T00:00:00Z,2025-05-01T01:00:00Z,40.7580,-73.9850,TimesSquare,291.6000
2025-05-01T16:00:00Z,2025-05-01T17:00:00Z,40.7580,-73.9850,TimesSquare,293.6300
2025-04-30T23:00:00Z,2025-05-01T00:00:00Z,40.7580,-73.9850,TimesSquare,292.6500
2025-05-01T22:00:00Z,2025-05-01T23:00:00Z,40.7580,-73.9850,TimesSquare,289.6300

Molto più leggibile.

3. Formati di risposta

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

  • 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 non specifichi un formato, il default è text/csv.

Codice:

curl -X POST 'https://gribstream.com/api/v2/gfs/timeseries' \
-H "Authorization: Bearer [API_TOKEN]" \
-H "Accept: text/csv" \
-d '{
    "fromTime": "2025-05-01T00:00:00Z",
    "untilTime": "2025-05-02T00:00:00Z",
    "coordinates": [{ "lat": 40.758, "lon": -73.985 , "name": "TimesSquare"}],
    "variables": [{ "name": "TMP", "level": "2 m above ground", "info": "", "alias": "temp" }]
}'

Risultato:

forecasted_at,forecasted_time,lat,lon,name,temp
2025-05-01T05:00:00Z,2025-05-01T06:00:00Z,40.7580,-73.9850,TimesSquare,287.7400
2025-05-01T10:00:00Z,2025-05-01T11:00:00Z,40.7580,-73.9850,TimesSquare,285.7200
2025-05-01T03:00:00Z,2025-05-01T04:00:00Z,40.7580,-73.9850,TimesSquare,289.1600
2025-05-01T08:00:00Z,2025-05-01T09:00:00Z,40.7580,-73.9850,TimesSquare,285.7200
2025-05-01T20:00:00Z,2025-05-01T21:00:00Z,40.7580,-73.9850,TimesSquare,291.7000
2025-05-01T04:00:00Z,2025-05-01T05:00:00Z,40.7580,-73.9850,TimesSquare,288.4300
2025-05-01T02:00:00Z,2025-05-01T03:00:00Z,40.7580,-73.9850,TimesSquare,290.1200
2025-05-01T09:00:00Z,2025-05-01T10:00:00Z,40.7580,-73.9850,TimesSquare,285.4300
2025-05-01T06:00:00Z,2025-05-01T07:00:00Z,40.7580,-73.9850,TimesSquare,286.8900
2025-05-01T19:00:00Z,2025-05-01T20:00:00Z,40.7580,-73.9850,TimesSquare,292.5500
2025-05-01T07:00:00Z,2025-05-01T08:00:00Z,40.7580,-73.9850,TimesSquare,286.3500
2025-05-01T15:00:00Z,2025-05-01T16:00:00Z,40.7580,-73.9850,TimesSquare,292.9300
2025-05-01T11:00:00Z,2025-05-01T12:00:00Z,40.7580,-73.9850,TimesSquare,286.8000
2025-05-01T18:00:00Z,2025-05-01T19:00:00Z,40.7580,-73.9850,TimesSquare,293.4100
2025-05-01T17:00:00Z,2025-05-01T18:00:00Z,40.7580,-73.9850,TimesSquare,293.8500
2025-05-01T12:00:00Z,2025-05-01T13:00:00Z,40.7580,-73.9850,TimesSquare,288.1300
2025-05-01T21:00:00Z,2025-05-01T22:00:00Z,40.7580,-73.9850,TimesSquare,291.0500
2025-05-01T13:00:00Z,2025-05-01T14:00:00Z,40.7580,-73.9850,TimesSquare,290.2100
2025-05-01T14:00:00Z,2025-05-01T15:00:00Z,40.7580,-73.9850,TimesSquare,291.3900
2025-05-01T01:00:00Z,2025-05-01T02:00:00Z,40.7580,-73.9850,TimesSquare,291.2300
2025-05-01T00:00:00Z,2025-05-01T01:00:00Z,40.7580,-73.9850,TimesSquare,291.6000
2025-05-01T16:00:00Z,2025-05-01T17:00:00Z,40.7580,-73.9850,TimesSquare,293.6300
2025-04-30T23:00:00Z,2025-05-01T00:00:00Z,40.7580,-73.9850,TimesSquare,292.6500
2025-05-01T22:00:00Z,2025-05-01T23:00:00Z,40.7580,-73.9850,TimesSquare,289.6300

Codice:

curl -X POST 'https://gribstream.com/api/v2/gfs/timeseries' \
-H "Authorization: Bearer [API_TOKEN]" \
-H "Accept: application/json" \
-d '{
    "fromTime": "2025-05-01T00:00:00Z",
    "untilTime": "2025-05-02T00:00:00Z",
    "coordinates": [{ "lat": 40.758, "lon": -73.985 , "name": "TimesSquare"}],
    "variables": [{ "name": "TMP", "level": "2 m above ground", "info": "", "alias": "temp" }]
}'

Risultato:

[{"forecasted_at":"2025-05-01T00:00:00Z","forecasted_time":"2025-05-01T00:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":292.96841796875}
,{"forecasted_at":"2025-05-01T06:00:00Z","forecasted_time":"2025-05-01T11:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":286.553857421875}
,{"forecasted_at":"2025-05-01T00:00:00Z","forecasted_time":"2025-05-01T05:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":288.80002441406253}
,{"forecasted_at":"2025-05-01T00:00:00Z","forecasted_time":"2025-05-01T04:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":289.4754296875}
,{"forecasted_at":"2025-05-01T12:00:00Z","forecasted_time":"2025-05-01T17:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":293.86765136718753}
,{"forecasted_at":"2025-05-01T12:00:00Z","forecasted_time":"2025-05-01T13:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":289.46726074218753}
,{"forecasted_at":"2025-05-01T12:00:00Z","forecasted_time":"2025-05-01T14:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":290.99106445312503}
,{"forecasted_at":"2025-05-01T18:00:00Z","forecasted_time":"2025-05-01T19:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":292.7922607421875}
,{"forecasted_at":"2025-05-01T18:00:00Z","forecasted_time":"2025-05-01T18:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":293.53837890625005}
,{"forecasted_at":"2025-05-01T18:00:00Z","forecasted_time":"2025-05-01T20:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":292.33542480468753}
,{"forecasted_at":"2025-05-01T12:00:00Z","forecasted_time":"2025-05-01T15:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":292.29106445312505}
,{"forecasted_at":"2025-05-01T18:00:00Z","forecasted_time":"2025-05-01T21:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":291.802685546875}
,{"forecasted_at":"2025-05-01T06:00:00Z","forecasted_time":"2025-05-01T09:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":286.70000000000005}
,{"forecasted_at":"2025-05-01T06:00:00Z","forecasted_time":"2025-05-01T06:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":288.23271484375}
,{"forecasted_at":"2025-05-01T06:00:00Z","forecasted_time":"2025-05-01T07:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":287.70000000000005}
,{"forecasted_at":"2025-05-01T18:00:00Z","forecasted_time":"2025-05-01T22:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":290.953857421875}
,{"forecasted_at":"2025-05-01T06:00:00Z","forecasted_time":"2025-05-01T08:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":287.1672607421875}
,{"forecasted_at":"2025-05-01T06:00:00Z","forecasted_time":"2025-05-01T10:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":286.2595458984375}
,{"forecasted_at":"2025-05-01T12:00:00Z","forecasted_time":"2025-05-01T12:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":287.74045410156253}
,{"forecasted_at":"2025-05-01T12:00:00Z","forecasted_time":"2025-05-01T16:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":293.20000000000005}
,{"forecasted_at":"2025-05-01T00:00:00Z","forecasted_time":"2025-05-01T02:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":291.348046875}
,{"forecasted_at":"2025-05-01T00:00:00Z","forecasted_time":"2025-05-01T03:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":290.47107421875}
,{"forecasted_at":"2025-05-01T00:00:00Z","forecasted_time":"2025-05-01T01:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":292.25318359375}
,{"forecasted_at":"2025-05-01T18:00:00Z","forecasted_time":"2025-05-01T23:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":290.0113037109375}
]

Codice:

curl -X POST 'https://gribstream.com/api/v2/gfs/timeseries' \
-H "Authorization: Bearer [API_TOKEN]" \
-H "Accept: application/ndjson" \
-d '{
    "fromTime": "2025-05-01T00:00:00Z",
    "untilTime": "2025-05-02T00:00:00Z",
    "coordinates": [{ "lat": 40.758, "lon": -73.985 , "name": "TimesSquare"}],
    "variables": [{ "name": "TMP", "level": "2 m above ground", "info": "", "alias": "temp" }]
}'

Risultato:

{"forecasted_at":"2025-05-01T12:00:00Z","forecasted_time":"2025-05-01T12:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":287.74045410156253}
{"forecasted_at":"2025-05-01T00:00:00Z","forecasted_time":"2025-05-01T05:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":288.80002441406253}
{"forecasted_at":"2025-05-01T12:00:00Z","forecasted_time":"2025-05-01T15:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":292.29106445312505}
{"forecasted_at":"2025-05-01T06:00:00Z","forecasted_time":"2025-05-01T06:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":288.23271484375}
{"forecasted_at":"2025-05-01T12:00:00Z","forecasted_time":"2025-05-01T16:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":293.20000000000005}
{"forecasted_at":"2025-05-01T18:00:00Z","forecasted_time":"2025-05-01T22:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":290.953857421875}
{"forecasted_at":"2025-05-01T00:00:00Z","forecasted_time":"2025-05-01T01:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":292.25318359375}
{"forecasted_at":"2025-05-01T00:00:00Z","forecasted_time":"2025-05-01T02:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":291.348046875}
{"forecasted_at":"2025-05-01T00:00:00Z","forecasted_time":"2025-05-01T03:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":290.47107421875}
{"forecasted_at":"2025-05-01T12:00:00Z","forecasted_time":"2025-05-01T13:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":289.46726074218753}
{"forecasted_at":"2025-05-01T00:00:00Z","forecasted_time":"2025-05-01T04:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":289.4754296875}
{"forecasted_at":"2025-05-01T12:00:00Z","forecasted_time":"2025-05-01T14:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":290.99106445312503}
{"forecasted_at":"2025-05-01T00:00:00Z","forecasted_time":"2025-05-01T00:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":292.96841796875}
{"forecasted_at":"2025-05-01T06:00:00Z","forecasted_time":"2025-05-01T07:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":287.70000000000005}
{"forecasted_at":"2025-05-01T12:00:00Z","forecasted_time":"2025-05-01T17:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":293.86765136718753}
{"forecasted_at":"2025-05-01T06:00:00Z","forecasted_time":"2025-05-01T08:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":287.1672607421875}
{"forecasted_at":"2025-05-01T18:00:00Z","forecasted_time":"2025-05-01T18:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":293.53837890625005}
{"forecasted_at":"2025-05-01T06:00:00Z","forecasted_time":"2025-05-01T09:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":286.70000000000005}
{"forecasted_at":"2025-05-01T18:00:00Z","forecasted_time":"2025-05-01T19:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":292.7922607421875}
{"forecasted_at":"2025-05-01T06:00:00Z","forecasted_time":"2025-05-01T10:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":286.2595458984375}
{"forecasted_at":"2025-05-01T18:00:00Z","forecasted_time":"2025-05-01T20:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":292.33542480468753}
{"forecasted_at":"2025-05-01T18:00:00Z","forecasted_time":"2025-05-01T21:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":291.802685546875}
{"forecasted_at":"2025-05-01T06:00:00Z","forecasted_time":"2025-05-01T11:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":286.553857421875}
{"forecasted_at":"2025-05-01T18:00:00Z","forecasted_time":"2025-05-01T23:00:00Z","lat":40.758,"lon":-73.985,"name":"TimesSquare","temp":290.0113037109375}
4. Selezionare orari espliciti invece di un intervallo

A volte è utile selezionare una lista di orari specifici invece di un intervallo continuo. Per questo puoi usare timesList nella richiesta. Su /timeseries, ogni valore è un orario di validità da restituire, cioè un valore di forecasted_time.

Per esempio, interroghiamo il meteo a Capodanno 🎉🥳🕛🍾🥂 2022, 2023, 2024 e 2025.

Codice:

curl -X POST 'https://gribstream.com/api/v2/gfs/timeseries' \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "timesList": [
        "2022-01-01T00:00:00Z",
        "2023-01-01T00:00:00Z",
        "2024-01-01T00:00:00Z",
        "2025-01-01T00:00:00Z"
    ],
    "coordinates": [{ "lat": 40.758, "lon": -73.985 , "name": "TimesSquare"}],
    "variables": [{ "name": "TMP", "level": "2 m above ground", "info": "", "alias": "temp" }]
}'

Risultato:

forecasted_at,forecasted_time,lat,lon,name,temp
2022-01-01T00:00:00Z,2022-01-01T00:00:00Z,40.7580,-73.9850,TimesSquare,283.1841
2024-01-01T00:00:00Z,2024-01-01T00:00:00Z,40.7580,-73.9850,TimesSquare,279.0649
2023-01-01T00:00:00Z,2023-01-01T00:00:00Z,40.7580,-73.9850,TimesSquare,281.7180
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,40.7580,-73.9850,TimesSquare,281.8039
5. Selezionare località con una griglia

Invece di interrogare coordinate specifiche, puoi definire una griglia con minLatitude, maxLatitude, minLongitude, maxLongitude e step, dove step è la risoluzione in gradi.

Un esempio visivo utile è la demo dei campi di vento su griglia.

Codice:

curl -X POST 'https://gribstream.com/api/v2/gfs/timeseries' \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "timesList": [ "2025-01-01T00:00:00Z" ],
    "grid": {
        "minLatitude": 25.00,
        "maxLatitude": 27.00,
        "minLongitude": -122.00,
        "maxLongitude": -120.00,
        "step": 0.5
    },
    "variables": [{ "name": "TMP", "level": "2 m above ground", "info": "", "alias": "temp" }]
}'

Risultato:

forecasted_at,forecasted_time,lat,lon,name,temp
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,27.0000,-122.0000,,290.0439
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,27.0000,-121.5000,,289.8739
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,27.0000,-121.0000,,289.7339
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,27.0000,-120.5000,,289.6239
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,27.0000,-120.0000,,289.5039
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,26.5000,-122.0000,,290.2839
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,26.5000,-121.5000,,290.1139
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,26.5000,-121.0000,,289.9739
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,26.5000,-120.5000,,289.8339
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,26.5000,-120.0000,,289.7239
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,26.0000,-122.0000,,290.5739
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,26.0000,-121.5000,,290.4239
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,26.0000,-121.0000,,290.2439
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,26.0000,-120.5000,,290.0339
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,26.0000,-120.0000,,289.8339
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,25.5000,-122.0000,,290.9539
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,25.5000,-121.5000,,290.7239
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,25.5000,-121.0000,,290.4739
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,25.5000,-120.5000,,290.2339
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,25.5000,-120.0000,,290.0439
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,25.0000,-122.0000,,291.1239
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,25.0000,-121.5000,,290.9539
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,25.0000,-121.0000,,290.7139
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,25.0000,-120.5000,,290.4539
2025-01-01T00:00:00Z,2025-01-01T00:00:00Z,25.0000,-120.0000,,290.2239
6. Filtro per lead time (minLeadTime, maxLeadTime)

Il lead time è la differenza tra il momento in cui una previsione è stata emessa (forecasted_at, il run del modello) e l'orario che quella previsione descrive (forecasted_time, l'orario di validità).

  • minLeadTime: include solo valori previsti almeno con questo anticipo, per esempio "12h" o "45m".
  • maxLeadTime: include solo valori previsti al massimo con questo anticipo, per esempio "3h".

In altre parole, questi parametri controllano il lead time minimo e massimo per ogni valore di previsione restituito. minHorizon/maxHorizon sono alias legacy deprecati che accettano ore intere.

Esempio: per vedere solo valori previsti almeno 12 ore prima:

Codice:

curl -X POST 'https://gribstream.com/api/v2/nbm/timeseries' \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "fromTime": "2025-05-01T12:00:00Z",
    "untilTime": "2025-05-01T18:00:00Z",
    "minLeadTime": "12h",
    "coordinates": [{ "lat": 40.758, "lon": -73.985, "name": "TimesSquare" }],
    "variables": [{ "name": "TMP", "level": "2 m above ground", "alias": "temp" }]
}'

Risultato:

forecasted_at,forecasted_time,lat,lon,name,temp,horizon_hours
            2025-05-01T00:00:00Z,2025-05-01T12:00:00Z,40.7580,-73.9850,TimesSquare,286.6700
            2025-05-01T01:00:00Z,2025-05-01T13:00:00Z,40.7580,-73.9850,TimesSquare,288.0300
            2025-05-01T02:00:00Z,2025-05-01T14:00:00Z,40.7580,-73.9850,TimesSquare,289.5900
            2025-05-01T03:00:00Z,2025-05-01T15:00:00Z,40.7580,-73.9850,TimesSquare,290.9600
            2025-05-01T04:00:00Z,2025-05-01T16:00:00Z,40.7580,-73.9850,TimesSquare,292.3300
            2025-05-01T05:00:00Z,2025-05-01T17:00:00Z,40.7580,-73.9850,TimesSquare,293.1900

Nota: qui le righe sono ordinate per forecasted_at per rendere il risultato più leggibile.

Altro esempio: per includere solo previsioni a breve termine fino a 3 ore: 

curl -X POST 'https://gribstream.com/api/v2/nbm/timeseries' \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "fromTime": "2025-05-01T12:00:00Z",
    "untilTime": "2025-05-01T15:00:00Z",
    "maxLeadTime": "3h",
    "coordinates": [{ "lat": 40.758, "lon": -73.985 }],
    "variables": [{ "name": "TMP", "level": "2 m above ground" }]
}'

Usa minLeadTime e maxLeadTime insieme per limitare i valori restituiti a qualsiasi finestra di previsione desiderata.

Suggerimento: a differenza di asOf (vedi l'esempio successivo), che limita i risultati ai dati disponibili prima di un certo momento, minLeadTime e maxLeadTime filtrano in base all'anticipo della previsione rispetto al valore previsto.

7. asOf o time-travel per backtesting

Quando fai backtesting di modelli predittivi, è essenziale interrogare i dati come erano conosciuti in un momento specifico, non dopo il fatto.

Per esempio: “Qual era la previsione per il 1 maggio, basata su ciò che era disponibile entro il 30 aprile alle 12:00 UTC?”

Questa è una richiesta time-travel: asOf è il timestamp di cutoff/riferimento, quindi sono idonei solo i run del modello generati in quel momento o prima, senza correzioni o aggiornamenti successivi.

Codice:

curl -X POST 'https://gribstream.com/api/v2/nbm/timeseries' \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "fromTime": "2025-05-01T00:00:00Z",
    "untilTime": "2025-05-02T00:00:00Z",
    "asOf": "2025-05-01T12:00:00Z",
    "coordinates": [{ "lat": 40.758, "lon": -73.985 , "name": "TimesSquare"}],
    "variables": [{ "name": "TMP", "level": "2 m above ground", "info": "", "alias": "temp" }]
}'

Risultato:

forecasted_at,forecasted_time,lat,lon,name,temp
2025-04-30T23:00:00Z,2025-05-01T00:00:00Z,40.7580,-73.9850,TimesSquare,292.6500
2025-05-01T00:00:00Z,2025-05-01T01:00:00Z,40.7580,-73.9850,TimesSquare,291.6000
2025-05-01T01:00:00Z,2025-05-01T02:00:00Z,40.7580,-73.9850,TimesSquare,291.2300
2025-05-01T02:00:00Z,2025-05-01T03:00:00Z,40.7580,-73.9850,TimesSquare,290.1200
2025-05-01T03:00:00Z,2025-05-01T04:00:00Z,40.7580,-73.9850,TimesSquare,289.1600
2025-05-01T04:00:00Z,2025-05-01T05:00:00Z,40.7580,-73.9850,TimesSquare,288.4300
2025-05-01T05:00:00Z,2025-05-01T06:00:00Z,40.7580,-73.9850,TimesSquare,287.7400
2025-05-01T06:00:00Z,2025-05-01T07:00:00Z,40.7580,-73.9850,TimesSquare,286.8900
2025-05-01T07:00:00Z,2025-05-01T08:00:00Z,40.7580,-73.9850,TimesSquare,286.3500
2025-05-01T08:00:00Z,2025-05-01T09:00:00Z,40.7580,-73.9850,TimesSquare,285.7200
2025-05-01T09:00:00Z,2025-05-01T10:00:00Z,40.7580,-73.9850,TimesSquare,285.4300
2025-05-01T10:00:00Z,2025-05-01T11:00:00Z,40.7580,-73.9850,TimesSquare,285.7200
2025-05-01T11:00:00Z,2025-05-01T12:00:00Z,40.7580,-73.9850,TimesSquare,286.8000
2025-05-01T12:00:00Z,2025-05-01T13:00:00Z,40.7580,-73.9850,TimesSquare,288.1300
2025-05-01T12:00:00Z,2025-05-01T14:00:00Z,40.7580,-73.9850,TimesSquare,290.1600
2025-05-01T12:00:00Z,2025-05-01T15:00:00Z,40.7580,-73.9850,TimesSquare,291.3400
2025-05-01T12:00:00Z,2025-05-01T16:00:00Z,40.7580,-73.9850,TimesSquare,292.6500
2025-05-01T12:00:00Z,2025-05-01T17:00:00Z,40.7580,-73.9850,TimesSquare,293.0100
2025-05-01T12:00:00Z,2025-05-01T18:00:00Z,40.7580,-73.9850,TimesSquare,293.1500
2025-05-01T12:00:00Z,2025-05-01T19:00:00Z,40.7580,-73.9850,TimesSquare,292.7500
2025-05-01T12:00:00Z,2025-05-01T20:00:00Z,40.7580,-73.9850,TimesSquare,292.1500
2025-05-01T12:00:00Z,2025-05-01T21:00:00Z,40.7580,-73.9850,TimesSquare,291.3500
2025-05-01T12:00:00Z,2025-05-01T22:00:00Z,40.7580,-73.9850,TimesSquare,290.7100
2025-05-01T12:00:00Z,2025-05-01T23:00:00Z,40.7580,-73.9850,TimesSquare,289.5800

Nota: qui le righe sono ordinate per forecasted_at per rendere il risultato più leggibile.

Questo esempio usa il NOAA National Blend of Models (NBM), che gira ogni ora. Nota che forecasted_at è sempre l'ora precedente a forecasted_time, cioè la migliore previsione per quell'ora, tranne per gli orari dopo asOf, impostato a 2025-05-01T12:00:00Z. I run del modello successivi sono esclusi.

8. Espressioni calcolate (valori derivati, campi calcolati, formule)

GribStream permette di definire espressioni per calcolare colonne derivate, trasformazioni e filtri booleani nelle richieste verso l'API.

Le espressioni usano il linguaggio expr, con operazioni numeriche, logiche e su string, più accesso a funzioni matematiche.

Per vedere una demo con dashboard che usa una sola richiesta API: simulazione della crescita del mais.

Funzionalità

  • Usa colonne del dataset ed espressioni calcolate in precedenza come input
  • Concatena espressioni: le espressioni successive possono usare i risultati di quelle precedenti
  • Applica filtri booleani per includere o escludere righe
  • Usa le funzioni matematiche registrate da GribStream

Espressioni di esempio

  • Velocità del vento da componenti U/V: func.Hypot(uwind, vwind)
  • Direzione del vento in gradi meteorologici: int(270 - func.Atan2(vwind, uwind) * 180 / 3.14159) % 360
  • Filtro per vento forte in superficie: func.Hypot(uwind, vwind) > 10

Codice:

curl -X POST 'https://gribstream.com/api/v2/hrrr/timeseries' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "fromTime": "2024-09-10T00:00:00Z",
    "untilTime": "2024-09-10T10:00:00Z",
    "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" }
    ]
}'

Risultato:

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-10T01:00:00Z,2024-09-10T02:00:00Z,40.7306,-73.9352,New York City,8.1815,1.6363,258,8.3435
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-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-10T03:00:00Z,2024-09-10T04:00:00Z,40.7306,-73.9352,New York City,6.4841,2.5385,248,6.9633
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-10T08:00:00Z,2024-09-10T09:00:00Z,40.7306,-73.9352,New York City,5.9424,-0.6889,276,5.9822
2024-09-10T06:00:00Z,2024-09-10T07:00:00Z,40.7306,-73.9352,New York City,7.3567,1.5594,258,7.5201
2024-09-10T07:00:00Z,2024-09-10T08:00:00Z,40.7306,-73.9352,New York City,6.5438,0.7486,263,6.5864
9. Filtrare o cercare condizioni con espressioni calcolate

GribStream permette di definire espressioni per filtrare nello spazio e nel tempo, restituendo solo i dati che rispettano la condizione.

Le espressioni di filtro usano la stessa sintassi delle espressioni calcolate, ma devono valutare a true o false.

Per vedere una demo con dashboard che usa una sola richiesta API: storm chasing.

Codice:

curl -X POST 'https://gribstream.com/api/v2/gfs/timeseries' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "fromTime": "2024-09-10T00:00:00Z",
    "untilTime": "2024-09-10T10:00:00Z",
    "grid": {
            "minLatitude": 24.52,
            "maxLatitude": 49.38,
            "minLongitude": -124.77,
            "maxLongitude": -66.93,
            "step": 0.5
        },
        "variables": [
            {"name": "CAPE", "level": "180-0 mb above ground", "info": "", "alias": "cape"},
            {"name": "CIN", "level": "180-0 mb above ground", "info": "", "alias": "cin"}
        ],
        "expressions":[
            { "expression": "cape + cin", "alias": "storm_severity"}
        ],
        "filter":{"expression": "storm_severity >= 1200"}
}'

Risultato:

forecasted_at,forecasted_time,lat,lon,name,cape,cin,offset_hours,storm_severity
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,29.0200,-70.7700,,1337.0000,-1.6324,-5713.0000,1335.3676
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,29.0200,-70.2700,,1204.0000,-1.6324,-5713.0000,1202.3676
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,28.5200,-71.7700,,1432.0000,-0.6324,-5713.0000,1431.3676
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,28.5200,-71.2700,,1384.0000,-1.6324,-5713.0000,1382.3676
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,28.5200,-70.7700,,1355.0000,-0.6324,-5713.0000,1354.3676
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,28.5200,-70.2700,,1388.0000,-1.6324,-5713.0000,1386.3676
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,28.0200,-112.2700,,1599.0000,-148.6324,-5713.0000,1450.3676
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,28.0200,-111.2700,,1424.0000,-104.6324,-5713.0000,1319.3676
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,28.0200,-75.2700,,1328.0000,-0.6324,-5713.0000,1327.3676
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,28.0200,-74.7700,,1242.0000,-1.6324,-5713.0000,1240.3676
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,28.0200,-73.2700,,1327.0000,0.3676,-5713.0000,1327.3676
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,28.0200,-72.7700,,1471.0000,0.3676,-5713.0000,1471.3676
...
10. Recuperare i run di previsione

Tutti gli esempi precedenti usano l'endpoint timeseries, che prima si chiamava history. Il suo scopo è restituire la migliore previsione possibile per ogni orario. La migliore previsione è sempre quella più recente o, detto in modo equivalente, quella con il lead time più basso. Qui il lead time è la distanza tra l'orario del run del modello (forecasted_at) e l'orario di validità (forecasted_time). I parametri minLeadTime, maxLeadTime e asOf limitano quali run del modello vengono considerati, ma per ogni valore previsto viene scelto un solo run.

Se invece vuoi recuperare tutti i run di ogni valore, devi usare l'endpoint runs, che prima si chiamava forecasts.

POST https://gribstream.com/api/v2/[MODEL]/runs

Questo endpoint sceglie l'intervallo usando parametri chiamati forecastedFrom e forecastedUntil, per chiarire che i dati vengono selezionati in base all'orario del run del modello, lo stesso timestamp restituito come forecasted_at. Su /runs, anche timesList enumera orari di run del modello, utile quando cerchi cicli specifici.

Tutti gli altri parametri restano disponibili e invariati, tranne asOf, che non è disponibile su /runs. Puoi quindi filtrare con minLeadTime e maxLeadTime, definire espressioni con valori calcolati, filtrare usando quelle espressioni e così via. minHorizon/maxHorizon sono alias legacy deprecati che accettano ore intere.

Codice:

curl -X POST 'https://gribstream.com/api/v2/nbm/runs' \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "forecastedFrom": "2024-09-10T00:00:00Z",
    "forecastedUntil": "2024-09-10T03:00:00Z",
    "minLeadTime": "1h",
    "maxLeadTime": "3h",
    "coordinates": [
        { "lat": 47.6, "lon": -122.33 }
    ],
    "variables": [
        { "name": "TMP", "level": "2 m above ground", "info": "", "alias": "temp" },
        { "name": "WIND", "level": "10 m above ground", "info": "", "alias": "wind_speed" },
        { "name": "DPT", "level": "2 m above ground", "info": "", "alias": "dew_point" }
    ]
    }'

Risultato:

forecasted_at,forecasted_time,lat,lon,name,dew_point,temp,wind_speed
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,47.6000,-122.3300,,288.2500,294.2700,1.6000
2024-09-10T00:00:00Z,2024-09-10T02:00:00Z,47.6000,-122.3300,,288.4000,293.4800,1.6000
2024-09-10T00:00:00Z,2024-09-10T03:00:00Z,47.6000,-122.3300,,288.2600,293.0000,1.6000
2024-09-10T01:00:00Z,2024-09-10T02:00:00Z,47.6000,-122.3300,,288.3500,293.4900,1.6000
2024-09-10T01:00:00Z,2024-09-10T03:00:00Z,47.6000,-122.3300,,288.1800,292.9800,1.6000
2024-09-10T01:00:00Z,2024-09-10T04:00:00Z,47.6000,-122.3300,,288.1900,292.2100,1.2000
2024-09-10T02:00:00Z,2024-09-10T03:00:00Z,47.6000,-122.3300,,288.1600,292.9500,1.6000
2024-09-10T02:00:00Z,2024-09-10T04:00:00Z,47.6000,-122.3300,,288.3800,292.1800,1.2000
2024-09-10T02:00:00Z,2024-09-10T05:00:00Z,47.6000,-122.3300,,287.9300,291.2800,1.2000
2024-09-10T03:00:00Z,2024-09-10T04:00:00Z,47.6000,-122.3300,,288.3300,292.0300,1.2000
2024-09-10T03:00:00Z,2024-09-10T05:00:00Z,47.6000,-122.3300,,287.9400,291.4900,1.2000
2024-09-10T03:00:00Z,2024-09-10T06:00:00Z,47.6000,-122.3300,,287.8000,290.8100,1.2000

Nota: qui le righe sono ordinate per forecasted_at per rendere il risultato più leggibile. Nota che ogni run del modello ha restituito lead time da 1 a 3.

11. Interrogare previsioni ensemble e selezionare membri

Alcuni modelli in GribStream, come NOAA Global Ensemble Forecast System (GEFS Atmos) ed ECMWF Integrated Forecasting System - Ensemble Forecast (IFS Enfo), sono ensemble. Ogni run contiene 30-50 previsioni dei singoli membri, avviate da condizioni iniziali leggermente diverse. Guardare tutti i membri permette di quantificare l'incertezza (spread), costruire probabilità, per esempio "80% di probabilità di pioggia > 25 mm", e intercettare estremi a bassa probabilità che un singolo run deterministico potrebbe non mostrare.

Puoi scegliere uno o più membri dell'ensemble con il campo members. Se lo ometti, il default è restituire solo il membro 0, cioè la previsione di controllo.

Codice:

curl -X POST 'https://gribstream.com/api/v2/gefsatmos/timeseries' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "fromTime": "2021-02-24T00:00:00Z",
    "untilTime": "2021-02-24T12:00:00Z",
    "minLeadTime": "0h",
    "maxLeadTime": "3h",
    "coordinates": [
        { "lat": 40.75, "lon": -73.98, "name": "home"}
    ],
    "variables": [
        { "name": "TMP", "level": "2 m above ground", "info": "", "alias": "temp" }
    ],
    "members": [1,2,3]
}'

Risultato:

forecasted_at,forecasted_time,lat,lon,name,member,temp
2021-02-24T00:00:00Z,2021-02-24T00:00:00Z,40.7500,-73.9800,home,1,277.0675
2021-02-24T00:00:00Z,2021-02-24T00:00:00Z,40.7500,-73.9800,home,2,276.9957
2021-02-24T00:00:00Z,2021-02-24T00:00:00Z,40.7500,-73.9800,home,3,277.1360
2021-02-24T00:00:00Z,2021-02-24T03:00:00Z,40.7500,-73.9800,home,1,275.1206
2021-02-24T00:00:00Z,2021-02-24T03:00:00Z,40.7500,-73.9800,home,2,275.0662
2021-02-24T00:00:00Z,2021-02-24T03:00:00Z,40.7500,-73.9800,home,3,275.7054
2021-02-24T06:00:00Z,2021-02-24T06:00:00Z,40.7500,-73.9800,home,1,275.9707
2021-02-24T06:00:00Z,2021-02-24T06:00:00Z,40.7500,-73.9800,home,2,275.3141
2021-02-24T06:00:00Z,2021-02-24T06:00:00Z,40.7500,-73.9800,home,3,275.7535
2021-02-24T06:00:00Z,2021-02-24T09:00:00Z,40.7500,-73.9800,home,1,273.9249
2021-02-24T06:00:00Z,2021-02-24T09:00:00Z,40.7500,-73.9800,home,2,273.8208
2021-02-24T06:00:00Z,2021-02-24T09:00:00Z,40.7500,-73.9800,home,3,274.3771

Nota: qui le righe sono ordinate per forecasted_at per rendere il risultato più leggibile. Nota che ogni run del modello ha restituito lead time da 1 a 3.

12. Avanzato: scoprire dataset e selettori dal catalogo

Se conosci già il dataset e i selettori che ti servono, salta questa sezione e vai direttamente a /timeseries o /runs. È ancora il modo normale di usare GribStream.

Il catalogo serve per casi più avanzati: costruire richieste per dataset diversi, dashboard multi-modello, strumenti interni o applicazioni che devono scoprire selettori invece di fissarli direttamente nel codice.

Passo 1: elencare i dataset

curl 'https://gribstream.com/api/v2/catalog/datasets'

Questo restituisce metadati pubblici per ogni dataset: codice, nome completo, provider, tag, cadenza dei run, informazioni sull'archivio, link alle fonti e link alla pagina del modello e agli endpoint API corrispondenti.

[
  {
    "code": "gfs",
    "name": "GFS",
    "full_name": "Global Forecast System",
    "provider": "NOAA",
    "models_page_url": "/models/gfs",
    "api_timeseries_url": "/api/v2/gfs/timeseries",
    "api_runs_url": "/api/v2/gfs/runs"
  }
]

Passo 2: ispezionare i parametri di un dataset

curl 'https://gribstream.com/api/v2/catalog/datasets/ifsoper/parameters'

Ogni riepilogo di parametro include il codice breve esatto della fonte, il nome completo, le unità, il testo di sintesi e l'indicazione se il parametro ha più varianti di selettore. I codici dei parametri sono case-sensitive: se un dataset espone 100u, devi riusare esattamente 100u come restituito.

[
  {
    "short_name": "100u",
    "full_name": "100 metre U wind component",
    "units": "m s-1",
    "variation_count": 1
  }
]

Per ispezionare un parametro in dettaglio, incluse tutte le varianti e i selettori pronti da copiare:

curl 'https://gribstream.com/api/v2/catalog/datasets/ifsoper/parameters/100u'
{
  "short_name": "100u",
  "full_name": "100 metre U wind component",
  "variations": [
    {
      "selector": { "name": "100u", "level": "sfc", "info": "" },
      "selector_literal": "{\"name\":\"100u\",\"level\":\"sfc\",\"info\":\"\"}"
    }
  ]
}

Passo 3: risolvere un parametro condiviso tra dataset

Questo è il workflow di catalogo più avanzato. È utile quando la tua applicazione vuole un concetto condiviso, per esempio la velocità del vento a 10 m, ma dataset diversi lo espongono con selettori o espressioni diverse.

curl 'https://gribstream.com/api/v2/catalog/shared-parameters/wind_speed_10m?dataset=ifsoper&alias=wind'

La risposta include un frammento resolved_request leggibile da macchina che puoi copiare nel corpo della richiesta di previsione per quel dataset.

{
  "code": "wind_speed_10m",
  "resolved_dataset": "ifsoper",
  "resolved_supported": true,
  "resolved_request": {
    "variables": [
      { "name": "10u", "level": "sfc", "alias": "u_component", "hidden": true },
      { "name": "10v", "level": "sfc", "alias": "v_component", "hidden": true }
    ],
    "expressions": [
      { "expression": "func.Hypot(u_component, v_component)", "alias": "wind" }
    ]
  }
}

Quando hai selettori o un resolved_request, usali negli stessi endpoint /timeseries e /runs mostrati prima in questa guida.

Per lo schema completo del catalogo e altri esempi, vedi Endpoint, OpenAPI e la specifica grezza in /docs/openapi.yaml.

Per scenari non coperti da questa guida, scrivici a info@gribstream.com.