Documentación de la API de pronósticos meteorológicos

Esta API da acceso a datos de pronóstico meteorológico para todos los modelos. Puedes recuperar datos históricos y pronosticados indicando el rango de tiempo, las coordenadas y las variables de interés.

Puedes usar nuestro Python client en GitHub o construir tu propia integración con los detalles de abajo.

Si estás integrando GribStream con una herramienta de AI, empieza con GribStream para herramientas de AI.

Endpoint timeseries

Para una coordenada, un parámetro meteorológico y un rango de tiempo dados, hay múltiples valores pronosticados disponibles. Cada valor corresponde a un horizonte de pronóstico distinto (lead time), es decir, pronósticos hechos en distintos momentos del pasado.

La API devuelve, para cada punto de tiempo, el valor pronosticado con el horizonte de pronóstico más corto. Es decir, recibes el pronóstico más reciente y normalmente más preciso disponible en ese momento. En data science, esto suele llamarse serie de mejor pronóstico (best forecast) o nowcast.

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

Renombrado Antes /history. La ruta anterior todavía funciona.

Modelos disponibles

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 de la solicitud

Header	Valor	Comentario
`Content-Type`	`application/json`	Valor predeterminado y único válido.
`Accept`	Elige uno: `text/csv` `application/json` `application/ndjson`	Selecciona el formato de respuesta. Por defecto usa `text/csv`
`Accept-Encoding`	`gzip`	Opcional y recomendado para una respuesta comprimida
`Authorization`	`Bearer <token>`	Reemplaza <token> por tu token de autenticación

Parámetros del request body

El request body debe ser un objeto JSON con la siguiente estructura:

Parámetro	Tipo	Descripción	Obligatorio
`fromTime`	`string` (ISO 8601)	Hora de inicio del periodo de pronóstico.	Sí, (fromTime, untilTime) o timesList
`untilTime`	`string` (ISO 8601)	Hora de fin del periodo de pronóstico.	Sí, (fromTime, untilTime) o timesList
`timesList`	`array` de string (ISO 8601)	Lista explícita de tiempos válidos a devolver; cada valor corresponde a `forecasted_time`.	Sí, (fromTime, untilTime) o timesList
`asOf`	`string` (ISO 8601)	Momento de corte/referencia: solo se consideran ejecuciones del modelo generadas en o antes de ese timestamp.	No
`minLeadTime`	`string` (duration)	Lead time mínimo (inclusive). String de duración como `"45m"` o `"18h"`. Tiene prioridad sobre `minHorizon`/`maxHorizon`.	No
`maxLeadTime`	`string` (duration)	Lead time máximo (inclusive). String de duración como `"45m"` o `"18h"`. Tiene prioridad sobre `minHorizon`/`maxHorizon`.	No
`minHorizon`	`integer`	Obsoleto (usa `minLeadTime`). Lead time mínimo en horas (inclusive).	No
`maxHorizon`	`integer`	Obsoleto (usa `maxLeadTime`). Lead time máximo en horas (inclusive).	No
`coordinates`	`array` de `coordinate`	Lista de coordenadas geográficas. Opcional cuando se envía `grid`; también puedes enviar ambos.	Sí - se debe enviar al menos `coordinates` o `grid`
`grid`	objeto `grid`	Dominio rectangular regular. El servidor devuelve cada punto dentro de los límites con el `step` espacial indicado. Puede usarse junto con `coordinates`.	Sí - se debe enviar al menos `coordinates` o `grid`
`variables`	`array` de `variable`	Lista de parámetros meteorológicos que se quieren recuperar.	Sí
`expressions`	`array` de `expression`	Columnas calculadas en el servidor a partir de las variables solicitadas. Cada entrada se devuelve como su propia columna usando el alias indicado. Consulta la documentación	No
`filter`	objeto `filter`	Filtro booleano aplicado después de evaluar todas las `expressions`. Debe contener un único campo `expression` de tipo `string`. Las filas donde la expresión evalúa a `false` se omiten de la respuesta.	No
`members`	`array` de integer	Para modelos de ensemble (`gefsatmos`, `ifsenfo`, `ifswaef` …), esto selecciona qué miembros del ensemble se incluyen en la respuesta. Ejemplo: `"members": [2,3,4]`. Por defecto usa `[0]` y devuelve solo el miembro 0, el pronóstico de control.	No (solo modelos de ensemble)

NOTA: el tiempo seleccionado debe especificarse mediante el rango (fromTime, untilTime) o timesList

Objeto de coordenada

Campo	Tipo	Descripción	Obligatorio
`lat`	`float`	Latitud de la coordenada.	Sí
`lon`	`float`	Longitud de la coordenada.	Sí
`name`	`string`	Nombre opcional para la coordenada; se devuelve en la respuesta para ayudar a identificar la ubicación.	No

Objeto de grilla

Campo	Tipo	Descripción	Obligatorio
`minLatitude`	number	Borde sur (°N)	Sí
`maxLatitude`	number	Borde norte (°N)	Sí
`minLongitude`	number	Borde oeste (°E)	Sí
`maxLongitude`	number	Borde este (°E)	Sí
`step`	number	Resolución en grados decimales	Sí

Objeto de variable

Los campos name, level e info forman el selector exacto de la variable meteorológica. Copia esos valores del catálogo o de la página del modelo; son identificadores de API, no etiquetas para traducir.

Consulta la lista completa de parámetros disponibles por modelo.

Campo	Tipo	Descripción	Obligatorio
`name`	`string`	Código exacto del parámetro meteorológico del catálogo (por ejemplo, `"TMP"` para temperatura). No se traduce.	Sí
`level`	`string`	Nivel atmosférico o de superficie exacto del catálogo (por ejemplo, `"2 m above ground"`).	Sí
`info`	`string`	Diferenciador exacto cuando el modelo tiene varios parámetros con el mismo `name` y `level`. Déjalo vacío solo si el valor del catálogo está vacío.	No
`alias`	`string`	Alias opcional para la variable. Si se envía, se usa como header de columna en la respuesta.	No

Objeto de expresión

Campo	Tipo	Descripción	Obligatorio
`expression`	`string`	Crea columnas calculadas. Todas las variables seleccionadas se pueden referenciar por su alias. Consulta la documentación	Sí
`alias`	`string`	Nombre de columna usado en la respuesta para este resultado calculado.	Sí

Objeto de filtro

Campo	Tipo	Descripción	Obligatorio
`expression`	string	Expresión booleana en el mismo DSL usado por `expressions`. Puede referenciar aliases definidos antes en el request body.	Sí

Solicitud de ejemplo

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

Respuesta de ejemplo

El formato de respuesta está determinado por el header Accept. La API admite tres formatos de respuesta:

Accept: text/csv - la respuesta es un archivo CSV con los datos de pronóstico.
Accept: application/json - cada línea de la respuesta es un objeto JSON independiente.
Accept: application/ndjson - la respuesta es un único array JSON de objetos.

Si se incluye el header Accept-Encoding: gzip, la respuesta se comprime con gzip.

NOTA: la respuesta no está estrictamente ordenada.

Ejemplo de respuesta 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

Ejemplo de respuesta 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}
]

Ejemplo de respuesta NDJSON (delimitada por líneas)

{"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 de la respuesta:

Campo	Descripción
`forecasted_at`	Hora de ejecución del modelo: cuándo se generó o emitió el pronóstico.
`forecasted_time`	Tiempo válido: hora para la cual aplica el pronóstico.
`lat`	Latitud de la coordenada.
`lon`	Longitud de la coordenada.
`name`	Nombre enviado en la solicitud para el conjunto de coordenadas.
`uwind` `vwind` `wind_direction` `wind_magnitude`	Una columna por variable o expresión derivada. Las variables usan por defecto `[name]\|[level]\|[info]`.

Notas de uso

Todos los tiempos deben estar en formato ISO 8601 (por ejemplo, "2022-08-10T00:00:00Z").
Usa minLeadTime/maxLeadTime (preferido) o los parámetros obsoletos minHorizon/maxHorizon (horas) para restringir lead times.
Debes especificar al menos una ubicación (coordinates y/o grid) y una variable.
El parámetro asOf es un timestamp de corte para consultas retrospectivas. La API solo considera ejecuciones del modelo generadas en o antes de asOf, de modo que backtests y simulaciones no usen por accidente pronósticos emitidos más tarde. Si no se envía, se usan los últimos datos de pronóstico disponibles.

Autenticación

Debes incluir un token de autenticación válido en el header Authorization. Para obtener un token,

Incluye el token en los headers de la solicitud así:

Authorization: Bearer <token>

Comando cURL de ejemplo

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 los datos de pronóstico y muestra las primeras 20 líneas de la respuesta descomprimida.

Manejo de errores

Si hay un error en la solicitud, la API devuelve un mensaje de error con un código de estado HTTP apropiado.

Códigos de error comunes

Código de estado	Significado	Descripción
400 Bad Request	Parámetros de solicitud inválidos.	Ocurre cuando faltan parámetros obligatorios o tienen valores inválidos.
401 Unauthorized	Autenticación fallida.	Ocurre cuando el token de autenticación falta o es inválido.
429 Too Many Requests	Cuota excedida.	Ocurre cuando agotas la cuota. La respuesta incluye un header `Retry-After` con el tiempo de espera antes de reintentar.
500 Internal Server Error	Error del servidor.	Ocurre cuando hay un error al procesar la solicitud en el servidor.

Endpoint runs

Recupera todas las ejecuciones del modelo en un rango de tiempo, para una lista de coordenadas y parámetros meteorológicos. Opcionalmente filtra por un rango de horas hacia adelante (horizontes mínimo/máximo).

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

Renombrado Antes /forecasts. La ruta anterior todavía funciona.