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 run idonei in base all'orario del run del modello, minLeadTime e maxLeadTime filtrano in base all'anticipo della previsione rispetto al valore previsto.

7. Cutoff sull'orario del run del modello con asOf per backtesting

Quando fai backtesting di modelli predittivi, spesso devi escludere cicli del modello generati dopo un momento decisionale storico.

Per esempio: “Qual era la previsione per il 1 maggio, usando solo run del modello generati entro il 30 aprile alle 12:00 UTC?”

asOf? è un cutoff sull'orario del run del modello: sono idonei solo i run generati in quel momento o prima. Non è un orario esatto di disponibilità nell'API in tempo reale; se conta la prima disponibilità reale, applica un margine conservativo basato sul ritardo abituale di pubblicazione del fornitore per gli orizzonti usati.

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.