GribStream

Guia de início rápido

Faça login, crie um token de API (há um plano gratuito) e envie sua primeira requisição. Copie e cole qualquer exemplo abaixo (cURL / Python). Troque o token e os horários e execute. Substitua [API_TOKEN] pelo seu token, sem os colchetes.

1. Fazer uma requisição simples

Consulte dados horários de temperatura para 1º de maio de 2025 na Times Square usando NOAA Global Forecast System (GFS).

URL:

Vamos enviar a requisição para este endpoint:

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

Renomeado Antes /history. O caminho anterior ainda funciona.

Substitua [MODEL] pelo código do GFS, gfs, para ficar assim:

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

Você pode ver todos os modelos disponíveis aqui.

Payload:

Os horários usam formato ISO 8601 UTC e vamos pedir um intervalo de tempo, de fromTime até untilTime.

As coordenadas são pares de números de ponto flutuante (latitude, longitude).

Os parâmetros meteorológicos são selecionados com tuplas (name, level, info). São seletores exatos do catálogo: name é o código de parâmetro do fornecedor, level é o nível vertical ou de superfície, e info desambigua variantes quando necessário. No GFS, você verá que a temperatura está disponível com TMP em muitos níveis. Vamos usar 2m above ground neste exemplo.

Código:

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)

Saída:

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

Observe que as linhas não são ordenadas por forecasted_at nem por forecasted_time. Isso melhora a eficiência da API.

2. Nomes de localizações e alias de variáveis

Ao processar a resposta, pode ser muito conveniente usar nomes em vez do par de coordenadas. Você pode dar à localização um nome legível ou armazenar um ID. Isso ajuda a criar visualizações e dashboards sem pré-processamento. Basta adicionar uma propriedade name a cada coordenada. Neste caso, vamos usar TimesSquare.

Da mesma forma, a convenção de três partes para nomear parâmetros meteorológicos pode ser difícil de ler (TMP|2 m above ground|), então você pode renomear a variável com uma propriedade extra chamada alias. Isso é útil para alternar programaticamente entre temperaturas em níveis diferentes e ainda chamar a coluna de temp. Pense nisso como a keyword as do SQL.

Código:

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)

Saída:

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

Bem mais legível.

3. Formatos de resposta

O formato de resposta é determinado pelo header HTTP Accept. A API aceita três formatos de resposta:

  • Accept: text/csv - a resposta é um arquivo CSV com os dados de previsão.
  • Accept: application/json - a resposta é um único array JSON de objetos.
  • Accept: application/ndjson - a resposta é JSON delimitado por linhas, com um objeto JSON por linha.

Se nenhum formato for especificado, o formato de resposta padrão é text/csv.

Código:

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" }]
}'

Saída:

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

Código:

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" }]
}'

Saída:

[{"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}
]

Código:

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" }]
}'

Saída:

{"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. Selecionar horários específicos em vez de um intervalo

Às vezes é útil selecionar uma lista de horários específicos em vez de um intervalo de tempo. Para isso, use o argumento timesList na requisição. Em /timeseries, cada valor é um horário válido que você quer receber, correspondente a forecasted_time.

Por exemplo, consulte o tempo durante o Ano Novo de 2022, 2023, 2024 e 2025.

Código:

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" }]
}'

Saída:

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. Selecionar localizações com uma grade

Em vez de consultar dados para coordenadas específicas, você pode definir uma grade com minLatitude, maxLatitude, minLongitude, maxLongitude e step, onde step é a resolução em graus.

Veja um exemplo visual na demo de campos de vento.

Código:

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" }]
}'

Saída:

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 por lead time (minLeadTime, maxLeadTime)

O lead time é a diferença entre o momento em que a previsão foi emitida (forecasted_at) e o horário previsto por ela (forecasted_time).

  • minLeadTime: inclui apenas valores previstos com pelo menos essa antecedência (por exemplo "12h", "45m").
  • maxLeadTime: inclui apenas valores previstos com no máximo essa antecedência (por exemplo "3h").

Em outras palavras, esses parâmetros controlam o lead time mínimo e máximo de cada valor previsto que você recupera (minHorizon/maxHorizon são aliases obsoletos que aceitam horas inteiras).

Exemplo: para ver apenas valores previstos com pelo menos 12 horas de antecedência:

Código:

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" }]
}'

Saída:

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

Observação: aqui as linhas são exibidas ordenadas por forecasted_at para facilitar a leitura do resultado.

Outro exemplo: para incluir apenas previsões de curto prazo até 3 horas: 

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" }]
}'

Use minLeadTime e maxLeadTime juntos para restringir os valores previstos à janela de previsão desejada.

Dica: ao contrário do parâmetro asOf (veja o próximo exemplo), que restringe os resultados aos dados disponíveis antes de certo horário, minLeadTime e maxLeadTime filtram pela idade da previsão em relação ao valor previsto.

7. Consultas retrospectivas com asOf (para backtesting)

Ao fazer backtesting de modelos preditivos, é essencial consultar os dados como eram conhecidos em um ponto específico no tempo, não depois dos fatos.

Por exemplo: “Qual era a previsão para 1º de maio, com base no que estava disponível em 30 de abril às 12:00 UTC?”

Isso é uma consulta retrospectiva: asOf define o horário de corte, portanto só são elegíveis execuções do modelo geradas nesse momento ou antes dele, sem correções ou atualizações posteriores.

Código:

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" }]
}'

Saída:

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

Observação: aqui as linhas são exibidas ordenadas por forecasted_at para facilitar a leitura do resultado.

Este exemplo usa NOAA National Blend of Models (NBM), que roda a cada hora. Observe que forecasted_at é sempre a hora anterior a forecasted_time, ou seja, a melhor previsão para aquela hora, exceto para horários depois de asOf, definido como 2025-05-01T12:00:00Z. Execuções do modelo posteriores a esse horário são excluídas.

8. Expressões calculadas (valores derivados, campos calculados, fórmulas, etc.)

O GribStream permite definir expressões para calcular colunas derivadas, transformações e filtros booleanos nas suas consultas à API.

As expressões usam a linguagem expr, com operações numéricas, lógicas e sobre strings, além de funções matemáticas.

Para ver um dashboard de demonstração que faz uma única requisição à API: simulação de crescimento do milho.

Funcionalidades

  • Usar colunas do dataset e expressões calculadas anteriormente como entradas
  • Encadear expressões: expressões posteriores podem usar resultados das anteriores
  • Aplicar filtros booleanos para incluir ou excluir linhas
  • Usar o conjunto de funções matemáticas registradas pelo GribStream (veja abaixo)

Exemplos de expressões

  • Velocidade do vento a partir de componentes U/V: func.Hypot(uwind, vwind)
  • Direção do vento em graus meteorológicos: int(270 - func.Atan2(vwind, uwind) * 180 / 3.14159) % 360
  • Filtro para vento forte em superfície: func.Hypot(uwind, vwind) > 10

Código:

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" }
    ]
}'

Saída:

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. Filtrar ou buscar condições com expressões calculadas

O GribStream permite definir expressões para filtrar no espaço e no tempo, retornando apenas dados que correspondem à condição.

Expressões de filtro seguem a mesma sintaxe das expressões calculadas, mas devem avaliar para true ou false.

Para ver um dashboard de demonstração que faz uma única requisição à API: caçadores de tempestades.

Código:

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"}
}'

Saída:

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. Recuperar execuções de modelo

Todos os exemplos anteriores usam o endpoint timeseries (antes history). O objetivo é retornar a melhor previsão possível para cada horário. A melhor previsão é sempre a mais recente, ou seja, a de menor lead time. Aqui lead time é a diferença entre o horário de execução do modelo (forecasted_at) e o horário válido (forecasted_time). Os parâmetros minLeadTime, maxLeadTime e asOf restringem quais execuções de modelo são consideradas, mas para cada valor previsto apenas uma execução é escolhida.

Quando queremos recuperar todas as execuções de cada valor, usamos o endpoint runs (antes forecasts).

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

Este endpoint escolhe o intervalo de tempo com os parâmetros forecastedFrom e forecastedUntil para deixar claro que os dados são selecionados pelo horário de execução do modelo, o mesmo horário retornado como forecasted_at. Em /runs, timesList também enumera horários de execução, útil ao procurar ciclos específicos.

Todos os outros parâmetros continuam disponíveis e iguais, exceto asOf, que não está disponível. Você pode filtrar por minLeadTime e maxLeadTime, definir expressões com valores calculados, filtrar por elas etc. (minHorizon/maxHorizon são aliases obsoletos que aceitam horas inteiras.)

Código:

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" }
    ]
    }'

Saída:

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

Observação: aqui as linhas são exibidas ordenadas por forecasted_at para facilitar a leitura do resultado. Observe que cada execução do modelo retorna horizontes 1 a 3.

11. Consultar previsões de ensemble e escolher membros

Alguns modelos no GribStream, como NOAA Global Ensemble Forecast System (GEFS Atmos) e ECMWF Integrated Forecasting System - Ensemble Forecast (IFS Enfo), são ensembles. Cada execução consiste em 30 a 50 membros do ensemble que partem de condições iniciais ligeiramente diferentes. Observar todos os membros permite quantificar incerteza (spread), criar probabilidades (por exemplo, “80 % de chance de chuva > 25 mm”) e detectar extremos de baixa probabilidade que uma execução determinística única poderia perder.

Você pode escolher um ou vários membros do ensemble com o campo members. Se ele não for especificado, o padrão é retornar apenas o membro 0, que é a previsão de controle.

Código:

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]
}'

Saída:

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

Observação: aqui as linhas são exibidas ordenadas por forecasted_at para facilitar a leitura do resultado. Observe que cada execução do modelo retorna horizontes 1 a 3.

12. Avançado: descobrir datasets e seletores pelo catálogo

Se você já sabe o dataset e os seletores que quer usar, pule esta seção e vá direto para /timeseries ou /runs. Essa ainda é a forma normal de usar o GribStream.

O catálogo é para casos mais avançados: construir seletores de datasets, dashboards multimodelo, ferramentas internas ou aplicações que precisam descobrir seletores em vez de fixá-los no código.

Passo 1: listar datasets

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

Isso retorna metadados públicos de cada dataset: código, nome completo, provedor, tags, cadência de execução, informações de arquivo, links das fontes e links para a página do modelo e os endpoints de API correspondentes.

[
  {
    "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: inspecionar parâmetros de um dataset

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

Cada resumo de parâmetro inclui o código curto exato da fonte, nome completo, unidades, resumo e se o parâmetro tem múltiplas variações de seletor. Códigos de parâmetros diferenciam maiúsculas e minúsculas; se um dataset expõe 100u, reutilize exatamente 100u como retornado.

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

Para inspecionar um parâmetro em detalhe, incluindo todas as variações e seletores prontos para copiar:

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: resolver um parâmetro compartilhado entre datasets

Este é o workflow de catálogo mais avançado. Ele é útil quando sua aplicação precisa de um conceito compartilhado, como velocidade do vento a 10 m, mas datasets diferentes o expõem com seletores ou expressões diferentes.

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

A resposta inclui um fragmento resolved_request em formato legível por máquina que você pode copiar para o payload de uma requisição de previsão desse 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" }
    ]
  }
}

Depois de ter seletores ou um resolved_request, use-os nos mesmos endpoints /timeseries e /runs mostrados antes neste guia.

Para o schema completo do catálogo e mais exemplos, veja Endpoints, OpenAPI e a especificação bruta em /docs/openapi.yaml.

Entre em contato para cenários não cobertos neste guia: info@gribstream.com.