Documentação da API de previsões meteorológicas

Esta API dá acesso a dados de previsão meteorológica para todos os modelos. Você pode recuperar dados históricos e previstos informando o intervalo de tempo, as coordenadas e as variáveis de interesse.

Você pode usar nosso cliente Python no GitHub ou criar sua própria integração com os detalhes abaixo.

Se estiver integrando o GribStream com uma ferramenta de IA, comece por GribStream para ferramentas de IA.

Endpoint /timeseries

Para uma coordenada, um parâmetro meteorológico e um intervalo de tempo, há vários valores previstos disponíveis. Cada valor corresponde a um horizonte de previsão diferente (lead time), representando previsões feitas em momentos diferentes no passado.

A API retorna, para cada horário válido, o valor previsto com o horizonte de previsão mais curto. Assim, você recebe a previsão mais recente e normalmente mais precisa disponível naquele momento. Em ciência de dados, isso costuma ser chamado de série de melhor previsão (best forecast) ou nowcast.

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

Renomeado Antes /history. O caminho anterior ainda funciona.

Modelos disponíveis

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

Headers HTTP da requisição

Header	Valor	Comentário
`Content-Type`	`application/json`	Valor padrão e único valor válido.
`Accept`	Escolha um: `text/csv` `application/json` `application/ndjson`	Seleciona o formato de resposta. Por padrão, usa `text/csv`.
`Accept-Encoding`	`gzip`	Opcional e recomendado para respostas grandes compactadas.
`Authorization`	`Bearer <token>`	Substitua <token> pelo seu token de autenticação.

Parâmetros do request body

O request body deve ser um objeto JSON com a seguinte estrutura:

Parâmetro	Tipo	Descrição	Obrigatório
`fromTime`	`string` (ISO 8601)	Horário de início do período de previsão.	Sim, (fromTime, untilTime) ou timesList
`untilTime`	`string` (ISO 8601)	Horário de fim do período de previsão.	Sim, (fromTime, untilTime) ou timesList
`timesList`	`array` de string (ISO 8601)	Lista explícita de horários válidos a retornar; cada valor corresponde a `forecasted_time`.	Sim, (fromTime, untilTime) ou timesList
`asOf`	`string` (ISO 8601)	Horário de corte: só são consideradas execuções do modelo geradas nesse momento ou antes dele. É o timestamp de referência usado pelo campo `asOf`.	Não
`minLeadTime`	`string` (duration)	Lead time (horizonte de previsão) mínimo, inclusive. Use uma string de duração como `"45m"` ou `"18h"`. Tem precedência sobre `minHorizon`/`maxHorizon`.	Não
`maxLeadTime`	`string` (duration)	Lead time (horizonte de previsão) máximo, inclusive. Use uma string de duração como `"45m"` ou `"18h"`. Tem precedência sobre `minHorizon`/`maxHorizon`.	Não
`minHorizon`	`integer`	Obsoleto (use `minLeadTime`). Lead time mínimo em horas, inclusive.	Não
`maxHorizon`	`integer`	Obsoleto (use `maxLeadTime`). Lead time máximo em horas, inclusive.	Não
`coordinates`	`array` de `coordinate`	Lista de coordenadas geográficas. Opcional quando `grid` é fornecido; você também pode enviar ambos.	Sim - ao menos `coordinates` ou `grid` deve ser fornecido
`grid`	objeto `grid`	Domínio retangular regular. O servidor retorna cada ponto dentro dos limites usando o valor de `step` informado. Pode ser usado junto com `coordinates`.	Sim - ao menos `coordinates` ou `grid` deve ser fornecido
`variables`	`array` de `variable`	Lista de parâmetros meteorológicos a recuperar.	Sim
`expressions`	`array` de `expression`	Colunas calculadas no servidor a partir das variáveis solicitadas. Cada entrada retorna como sua própria coluna usando o alias fornecido. Consulte a documentação	Não
`filter`	objeto `filter`	Filtro booleano aplicado depois que todas as `expressions` são avaliadas. Deve conter um único campo `expression` do tipo `string`. As linhas em que a expressão avalia para `false` são omitidas da resposta.	Não
`members`	`array` de integer	Para modelos de ensemble (`gefsatmos`, `ifsenfo`, `ifswaef` …), isto seleciona quais membros do ensemble serão incluídos na resposta. Exemplo: `"members": [2,3,4]`. Por padrão, usa `[0]` e retorna apenas o membro 0, a previsão de controle.	Não (somente modelos de ensemble)

Observação: o horário selecionado deve ser especificado pelo intervalo (fromTime, untilTime) ou por timesList.

Objeto de coordenada

Campo	Tipo	Descrição	Obrigatório
`lat`	`float`	Latitude da coordenada.	Sim
`lon`	`float`	Longitude da coordenada.	Sim
`name`	`string`	Nome opcional da coordenada; retornado na resposta para ajudar a identificar a localização.	Não

Objeto de grade

Campo	Tipo	Descrição	Obrigatório
`minLatitude`	number	Limite sul (°N)	Sim
`maxLatitude`	number	Limite norte (°N)	Sim
`minLongitude`	number	Limite oeste (°E)	Sim
`maxLongitude`	number	Limite leste (°E)	Sim
`step`	number	Resolução em graus decimais	Sim

Objeto de variável

Os campos name, level e info formam o seletor exato da variável meteorológica. Copie esses valores do catálogo ou da página do modelo; eles são identificadores de API, não rótulos para traduzir.

Consulte a lista completa de parâmetros disponíveis por modelo.

Campo	Tipo	Descrição	Obrigatório
`name`	`string`	Código exato do parâmetro meteorológico no catálogo (por exemplo, `"TMP"` para temperatura). Não traduza.	Sim
`level`	`string`	Nível atmosférico ou de superfície exato do catálogo (por exemplo, `"2 m above ground"`).	Sim
`info`	`string`	Diferenciador exato quando o modelo tem vários parâmetros com o mesmo `name` e `level`. Deixe vazio apenas se o valor do catálogo estiver vazio.	Não
`alias`	`string`	Alias opcional para a variável. Se fornecido, ele será usado como cabeçalho da coluna na resposta.	Não

Objeto de expressão

Campo	Tipo	Descrição	Obrigatório
`expression`	`string`	Cria colunas calculadas. Todas as variáveis selecionadas podem ser referenciadas pelo alias. Consulte a documentação	Sim
`alias`	`string`	Nome da coluna usado na resposta para este resultado calculado.	Sim

Objeto de filtro

Campo	Tipo	Descrição	Obrigatório
`expression`	string	Expressão booleana no mesmo DSL usado por `expressions`. Pode referenciar aliases definidos anteriormente dentro do request body.	Sim

Requisição de exemplo

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

Resposta de exemplo

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 o header Accept-Encoding: gzip for incluído, a resposta será comprimida com gzip.

Observação: a resposta não é estritamente ordenada.

Exemplo de resposta CSV

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

Exemplo de resposta JSON (array JSON)

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

Exemplo de resposta NDJSON (delimitada por linhas)

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

Campos da resposta:

Campo	Descrição
`forecasted_at`	Horário de execução do modelo: quando a previsão foi gerada ou emitida.
`forecasted_time`	Horário válido: horário ao qual a previsão se aplica.
`lat`	Latitude da coordenada.
`lon`	Longitude da coordenada.
`name`	Nome enviado na requisição para o conjunto de coordenadas.
`uwind` `vwind` `wind_direction` `wind_magnitude`	Uma coluna por variável ou expressão derivada. As variáveis usam por padrão `[name]\|[level]\|[info]`.

Notas de uso

Todos os horários devem estar no formato ISO 8601 (por exemplo, "2022-08-10T00:00:00Z").
Use minLeadTime/maxLeadTime (preferido) ou os parâmetros obsoletos minHorizon/maxHorizon (horas) para restringir lead times, ou seja, horizontes de previsão.
Você deve especificar pelo menos uma localização (coordinates e/ou grid) e uma variável.
O parâmetro asOf define o horário de corte para consultas retrospectivas. A API só considera execuções do modelo geradas em asOf ou antes dele, para que backtests e simulações não usem por acidente previsões emitidas depois. Se não for enviado, serão usados os dados de previsão mais recentes disponíveis.

Autenticação

Você precisa incluir um token de autenticação válido no header Authorization. Para obter um token,

Inclua o token nos headers HTTP da requisição assim:

Authorization: Bearer <token>

Comando cURL de exemplo

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

Este comando recupera os dados de previsão e mostra as primeiras 20 linhas da resposta descomprimida.

Tratamento de erros

Se houver um erro na requisição, a API retornará uma mensagem de erro com um código de status HTTP apropriado.

Códigos de erro comuns

Código de status	Significado	Descrição
400 Bad Request	Parâmetros de requisição inválidos.	Ocorre quando parâmetros obrigatórios estão ausentes ou têm valores inválidos.
401 Unauthorized	Falha na autenticação.	Ocorre quando o token de autenticação está ausente ou é inválido.
429 Too Many Requests	Cota excedida.	Ocorre quando você esgota a cota. A resposta inclui um header `Retry-After` com o tempo de espera antes de tentar novamente.
500 Internal Server Error	Erro do servidor.	Ocorre quando há um erro ao processar a requisição no servidor.

Endpoint /runs

Recupera todas as execuções do modelo em um intervalo de tempo, para uma lista de coordenadas e parâmetros meteorológicos. Opcionalmente, filtra por uma janela de lead time (horizonte mínimo/máximo).

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

Renomeado Antes /forecasts. O caminho anterior ainda funciona.