Documentación de la API de pronósticos meteorológicos históricos.

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 elegible más corto. Es decir, recibes la ejecución del modelo más reciente permitida por los filtros de la consulta, que normalmente es la predicción más útil. 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 y datasets disponibles

Consulta el catálogo de modelos para ver la lista actual de datasets compatibles, con sus códigos exactos para la API, parámetros, niveles y cobertura. Usa el código del dataset en el segmento <model> de la ruta anterior.

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)	Corte por hora de ejecución del modelo: solo se consideran ejecuciones 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`
`includeMetadata`	`string[]`	Array opcional en timeseries y runs. Usa native_coordinate para añadir native_lat y native_lon, index_updated_at para añadir index_updated_at, o pide ambos. No añade créditos por variables meteorológicas.	No
`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
`native_lat`, `native_lon`	lat y lon conservan la ubicación solicitada. native_lat y native_lon indican el centro de la celda elegida y se repiten en cada fila de esa ubicación. Las longitudes nativas siguen la convención de la grilla: 286° y −74° representan la misma longitud.
`index_updated_at`	Momento de la última actualización de la fila del índice, en UTC ISO 8601. Se incluye al pedir index_updated_at.
`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 cuatro formatos de respuesta:

Accept: text/csv - la respuesta es un archivo CSV con los datos de pronóstico.
Accept: application/json - la respuesta es un único array JSON de objetos.
Accept: application/ndjson - la respuesta es JSON delimitado por líneas, con un objeto JSON por línea.
Accept: application/vnd.apache.parquet - la respuesta es un archivo Parquet tipado y comprimido con ZSTD. También se aceptan los aliases application/x-parquet y application/parquet.

Parquet es binario, así que guárdalo en un archivo en lugar de imprimirlo en la terminal. Las columnas dinámicas conservan sus tipos y admiten valores nulos; las columnas de timestamp contienen valores UTC sin zona horaria y con resolución de segundos.

Para un resultado grande, añade ?delivery=url&format=csv, json, ndjson o parquet y envía Accept: application/json. El contenido JSON enviado no cambia y la API devuelve metadatos del archivo junto con una URL de descarga firmada y de corta duración. Sin estos parámetros, todos los formatos conservan su respuesta directa habitual.

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.
`native_lat`, `native_lon`	lat y lon conservan la ubicación solicitada. native_lat y native_lon indican el centro de la celda elegida y se repiten en cada fila de esa ubicación. Las longitudes nativas siguen la convención de la grilla: 286° y −74° representan la misma longitud.
`index_updated_at`	Momento de la última actualización de la fila del índice, en UTC ISO 8601. Se incluye al pedir index_updated_at.
`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 corte por hora de ejecución del modelo para consultas retrospectivas. La API solo considera ejecuciones del modelo generadas en o antes de asOf. No demuestra que los datos seleccionados ya estuvieran disponibles en GribStream en ese instante de reloj. 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.

Modelos y datasets disponibles

Consulta el catálogo de modelos para ver la lista actual de datasets compatibles, con sus códigos exactos para la API, parámetros, niveles y cobertura. Usa el código del dataset en el segmento <model> de la ruta anterior.

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
`forecastedFrom`	`string` (ISO 8601)	Primera hora de ejecución del modelo.	Sí, (forecastedFrom, forecastedUntil) o timesList
`forecastedUntil`	`string` (ISO 8601)	Última hora de ejecución del modelo.	Sí, (forecastedFrom, forecastedUntil) o timesList
`timesList`	`array` de string (ISO 8601)	Lista explícita de horas de ejecución del modelo; cada valor corresponde a `forecasted_at`.	Sí, (forecastedFrom, forecastedUntil) o timesList
`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.	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`
`includeMetadata`	`string[]`	Array opcional en timeseries y runs. Usa native_coordinate para añadir native_lat y native_lon, index_updated_at para añadir index_updated_at, o pide ambos. No añade créditos por variables meteorológicas.	No
`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 (forecastedFrom, forecastedUntil) o timesList

Objeto de coordenada

Campo	Tipo	Descripción	Obligatorio
`native_lat`, `native_lon`	lat y lon conservan la ubicación solicitada. native_lat y native_lon indican el centro de la celda elegida y se repiten en cada fila de esa ubicación. Las longitudes nativas siguen la convención de la grilla: 286° y −74° representan la misma longitud.
`index_updated_at`	Momento de la última actualización de la fila del índice, en UTC ISO 8601. Se incluye al pedir index_updated_at.
`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.

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/runs
Content-Type: application/json
Accept-Encoding: gzip
Authorization: Bearer <token>
Payload:
{
    "forecastedFrom": "2024-09-10T00:00:00Z",
    "forecastedUntil": "2024-09-10T00: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 cuatro formatos de respuesta:

Accept: text/csv - la respuesta es un archivo CSV con los datos de pronóstico.
Accept: application/json - la respuesta es un único array JSON de objetos.
Accept: application/ndjson - la respuesta es JSON delimitado por líneas, con un objeto JSON por línea.
Accept: application/vnd.apache.parquet - la respuesta es un archivo Parquet tipado y comprimido con ZSTD. También se aceptan los aliases application/x-parquet y application/parquet.

Parquet es binario, así que guárdalo en un archivo en lugar de imprimirlo en la terminal. Las columnas dinámicas conservan sus tipos y admiten valores nulos; las columnas de timestamp contienen valores UTC sin zona horaria y con resolución de segundos.

Para un resultado grande, añade ?delivery=url&format=csv, json, ndjson o parquet y envía Accept: application/json. El contenido JSON enviado no cambia y la API devuelve metadatos del archivo junto con una URL de descarga firmada y de corta duración. Sin estos parámetros, todos los formatos conservan su respuesta directa habitual.

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-10T00:00:00Z,2024-09-10T01:00:00Z,40.7306,-73.9352,New York City,8.0572,2.9389,249,8.5765
2024-09-10T00:00:00Z,2024-09-11T02:00:00Z,40.7306,-73.9352,New York City,2.3471,-5.2970,336,5.7937
2024-09-10T00:00:00Z,2024-09-10T03:00:00Z,40.7306,-73.9352,New York City,7.2268,1.7030,256,7.4247
2024-09-10T00:00:00Z,2024-09-11T06:00:00Z,40.7306,-73.9352,New York City,-2.9925,-5.0025,30,5.8292
2024-09-10T00:00:00Z,2024-09-11T07:00:00Z,40.7306,-73.9352,New York City,-2.9643,-4.9196,31,5.7437
2024-09-10T00:00:00Z,2024-09-10T12:00:00Z,40.7306,-73.9352,New York City,4.7834,-4.3696,312,6.4787
2024-09-10T00:00:00Z,2024-09-10T10:00:00Z,40.7306,-73.9352,New York City,7.2718,0.5647,265,7.2937
2024-09-10T00:00:00Z,2024-09-11T10:00:00Z,40.7306,-73.9352,New York City,-2.9361,-4.5728,32,5.4343
2024-09-10T00:00:00Z,2024-09-11T05:00:00Z,40.7306,-73.9352,New York City,-3.1221,-5.8816,27,6.6589
2024-09-10T00:00:00Z,2024-09-10T06:00:00Z,40.7306,-73.9352,New York City,6.6521,1.6799,255,6.8610
2024-09-10T00:00:00Z,2024-09-11T00:00:00Z,40.7306,-73.9352,New York City,3.2101,-3.3758,316,4.6584
2024-09-10T00:00:00Z,2024-09-10T11:00:00Z,40.7306,-73.9352,New York City,6.9390,-2.4367,289,7.3544
...

Ejemplo de respuesta JSON (array JSON)

[{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.078826904296875,"vwind":2.4223251342773438,"wind_direction":251,"wind_magnitude":7.481807896300802}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T07:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.181903839111328,"vwind":2.596050262451172,"wind_direction":247,"wind_magnitude":6.704879718622265}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-11T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":-2.627544403076172,"vwind":-5.187816619873047,"wind_direction":26,"wind_magnitude":5.815275648803582}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T08:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.091346740722656,"vwind":2.6632766723632812,"wind_direction":249,"wind_magnitude":7.5749746686515245}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T04:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.889509201049805,"vwind":2.7773094177246094,"wind_direction":248,"wind_magnitude":7.428242364996697}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T03:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.226800918579102,"vwind":1.7029743194580078,"wind_direction":256,"wind_magnitude":7.424740604863526}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T10:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.271799087524414,"vwind":0.5646705627441406,"wind_direction":265,"wind_magnitude":7.2936900683913555}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T12:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":4.783409118652344,"vwind":-4.369564056396484,"wind_direction":312,"wind_magnitude":6.4787416092446914}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T05:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.676166534423828,"vwind":2.414224624633789,"wind_direction":252,"wind_magnitude":8.046863563053401}
,{"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}
...
]

Ejemplo de respuesta NDJSON (delimitada por líneas)

{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T03:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.226800918579102,"vwind":1.7029743194580078,"wind_direction":256,"wind_magnitude":7.424740604863526}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T17:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":2.3053665161132812,"vwind":-3.231029510498047,"wind_direction":324,"wind_magnitude":3.969164455061737}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T19:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":1.7580318450927734,"vwind":-2.8487396240234375,"wind_direction":328,"wind_magnitude":3.3475354238366912}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T16:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":2.373655319213867,"vwind":-3.552021026611328,"wind_direction":326,"wind_magnitude":4.272129790622153}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T20:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":1.9354515075683594,"vwind":-2.271472930908203,"wind_direction":319,"wind_magnitude":2.9842187945922025}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T02:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.008834838867188,"vwind":1.1038799285888672,"wind_direction":262,"wind_magnitude":8.084552329782657}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T12:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":4.783409118652344,"vwind":-4.369564056396484,"wind_direction":312,"wind_magnitude":6.4787416092446914}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T04:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.889509201049805,"vwind":2.7773094177246094,"wind_direction":248,"wind_magnitude":7.428242364996697}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T13:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":2.683929443359375,"vwind":-4.015068054199219,"wind_direction":326,"wind_magnitude":4.829518478770162}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T18:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":1.8502693176269531,"vwind":-3.0554637908935547,"wind_direction":328,"wind_magnitude":3.5720240096076235}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-11T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":-2.627544403076172,"vwind":-5.187816619873047,"wind_direction":26,"wind_magnitude":5.815275648803582}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T14:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":1.9734878540039062,"vwind":-4.105434417724609,"wind_direction":334,"wind_magnitude":4.555134034047598}
...

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.
`native_lat`, `native_lon`	lat y lon conservan la ubicación solicitada. native_lat y native_lon indican el centro de la celda elegida y se repiten en cada fila de esa ubicación. Las longitudes nativas siguen la convención de la grilla: 286° y −74° representan la misma longitud.
`index_updated_at`	Momento de la última actualización de la fila del índice, en UTC ISO 8601. Se incluye al pedir index_updated_at.
`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.

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/runs' \
-H "Content-Type: application/json" \
-H "Accept-Encoding: gzip" \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "forecastedFrom": "2024-09-10T00:00:00Z",
    "forecastedUntil": "2024-09-10T00: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.

Cuota de créditos

GET https://gribstream.com/api/v2/quota

Consulta la cuota y el estado de tu token de API. Esta solicitud no consume créditos y sigue disponible si la cuota está agotada o el token está vencido o inactivo. Las credenciales ausentes, inválidas o revocadas devuelven 401.

curl -sS https://gribstream.com/api/v2/quota \
  -H 'Authorization: Bearer YOUR_TOKEN'

El uso corresponde al día UTC actual. Las solicitudes en curso registran créditos por lotes, por lo que el uso informado puede tener retraso. Los créditos restantes no son una reserva. El estado del token es independiente del agotamiento de la cuota; no se incluyen fechas de renovación ni vencimiento.

{
  "as_of": "2026-10-15T12:00:00Z",
  "usage_day_start_at": "2026-10-15T00:00:00Z",
  "quota_resets_at": "2026-10-16T00:00:00Z",
  "plan_id": 2,
  "plan_name": "Pro Plan",
  "token_status": "active",
  "credits_used": 12000,
  "plan_daily_limit": 48000,
  "overage_multiplier": 1.5,
  "effective_daily_limit": 72000,
  "credits_remaining": 60000,
  "unlimited": false,
  "quota_exhausted": false,
  "recommended_retry_at": null
}

effective_daily_limit es el límite del plan multiplicado por overage_multiplier y redondeado hacia arriba. credits_remaining nunca es negativo. Para tokens sin límite, ambos campos son null y quota_exhausted es false. Consulta OpenAPI para ver todos los campos de respuesta.

La cuota se restablece a las 00:00 UTC. Si está agotada, recommended_retry_at añade el mismo retraso estable por token de hasta una hora que usa Retry-After. En otro caso es null. El restablecimiento de la cuota no reactiva un token inactivo.

OpenAPI

Coordenadas de la grilla nativa

Devuelve todos los pares latitud/longitud nativos dentro de una caja inclusiva. Envía los cuatro límites; minLat no puede superar maxLat. Las longitudes aceptan −180..180 o 0..360; límites decrecientes cruzan el borde. No hay paginación. Copia lat/lon en coordinates de tu consulta.

GET https://gribstream.com/api/v2/<dataset>/native-coordinates

Headers de la solicitud

Header	Valor	Comentario
`Accept`	`text/csv application/json application/ndjson application/vnd.apache.parquet`	Selecciona el formato; usa CSV si se omite o no está soportado.
`Accept-Encoding`	`gzip`	Opcional; solicita una respuesta comprimida.
`Authorization`	`Bearer <token>`	Se requiere un token API registrado.

Parámetros de consulta

Parámetro	Tipo	Descripción	Obligatorio
`minLat`	`number`	Límite sur de latitud (inclusivo). `-90..90`	Sí
`maxLat`	`number`	Límite norte de latitud (inclusivo). `-90..90`	Sí
`minLon`	`number`	Límite oeste de longitud (inclusivo). `-180..360`	Sí
`maxLon`	`number`	Límite este de longitud (inclusivo). `-180..360`	Sí

Ejemplo de solicitud

curl --get 'https://gribstream.com/api/v2/gfs/native-coordinates' \
  -H 'Authorization: Bearer [API_TOKEN]' \
  -H 'Accept: application/json' \
  --data-urlencode 'minLat=40.7' \
  --data-urlencode 'maxLat=40.8' \
  --data-urlencode 'minLon=-74.1' \
  --data-urlencode 'maxLon=-73.9'

Ejemplos de respuesta

CSV es el formato predeterminado. Usa Accept: application/json para un array, application/ndjson (o application/x-ndjson) para JSON Lines o application/vnd.apache.parquet para Parquet. Todos contienen solo lat y lon. Las especificaciones de grilla están en el detalle gratuito del catálogo. delivery=url solo está disponible para consultas meteorológicas.

Ejemplo de respuesta CSV

lat,lon
40.75,286

Ejemplo de respuesta JSON

[
  {"lat": 40.75, "lon": 286}
]

Ejemplo de respuesta JSON Lines

{"lat":40.75,"lon":286}

Ejemplo de respuesta Parquet

Parquet es binario. Guárdalo en un archivo; sus únicas columnas son lat (DOUBLE) y lon (DOUBLE), con un par de coordenadas por fila.

curl --get 'https://gribstream.com/api/v2/gfs/native-coordinates' \
  -H 'Authorization: Bearer [API_TOKEN]' \
  -H 'Accept: application/vnd.apache.parquet' \
  --data-urlencode 'minLat=40.7' \
  --data-urlencode 'maxLat=40.8' \
  --data-urlencode 'minLon=-74.1' \
  --data-urlencode 'maxLon=-73.9' \
  --output native-coordinates.parquet

Campos de respuesta

Campo	Descripción
`lat, lon`	Latitud y longitud del centro de la celda nativa.

Notas de uso

Las longitudes nativas siguen la convención de la grilla: 286° y −74° representan la misma longitud.

Se requiere un token registrado. Cada consulta cuesta un crédito por 500 coordenadas devueltas, redondeado hacia arriba: la misma tarifa que un parámetro meteorológico en una fecha. Cajas vacías cuestan cero. Sin cuota gratuita. Sin cuota, devuelve 429 y Retry-After.

El stream puede detenerse al alcanzar la cuota, con un máximo de un crédito adicional (500 coordenadas) por consulta admitida. La respuesta sigue siendo HTTP 200 válida: CSV y JSON Lines terminan en la última fila, JSON cierra su array y Parquet finaliza el archivo. No se añaden estadísticas ni indicador de finalización.

Las imágenes satelitales incluyen píxeles que miran más allá de la Tierra. Solo se devuelven los que tienen ubicación geográfica. Las coordenadas describen centros de celdas, no disponibilidad de valores meteorológicos. AICON tiene un error de cuantización inferior a 0,5 m.

Códigos de error

Estado	Descripción
`400 Bad Request`	Caja ausente o inválida, o campos de paginación no soportados.
`401 Unauthorized`	Token ausente o inválido.
`403 Forbidden`	Los inventarios requieren un token registrado.
`404 Not Found`	Dataset desconocido.
`429 Too Many Requests`	Sin cuota disponible; respeta Retry-After.
`501 Not Implemented`	Geometría nativa no soportada.
`503 Service Unavailable`	Fuente de coordenadas temporalmente no disponible.

Referencia de la API del catálogo · OpenAPI

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

Endpoint timeseries

Modelos y datasets disponibles

Headers de la solicitud

Parámetros del request body

Objeto de coordenada

Objeto de grilla

Objeto de variable

Objeto de expresión

Objeto de filtro

Solicitud de ejemplo

Respuesta de ejemplo

Ejemplo de respuesta CSV

Ejemplo de respuesta JSON (array JSON)

Ejemplo de respuesta NDJSON (delimitada por líneas)

Notas de uso

Autenticación

Comando cURL de ejemplo

Manejo de errores

Códigos de error comunes

Endpoint runs

Modelos y datasets disponibles

Headers de la solicitud

Parámetros del request body

Objeto de coordenada

Objeto de grilla

Objeto de variable

Objeto de expresión

Objeto de filtro

Solicitud de ejemplo

Respuesta de ejemplo

Ejemplo de respuesta CSV

Ejemplo de respuesta JSON (array JSON)

Ejemplo de respuesta NDJSON (delimitada por líneas)

Notas de uso

Autenticación

Comando cURL de ejemplo

Manejo de errores

Códigos de error comunes

Cuota de créditos

Coordenadas de la grilla nativa

Headers de la solicitud

Parámetros de consulta

Ejemplo de solicitud

Ejemplos de respuesta

Ejemplo de respuesta CSV

Ejemplo de respuesta JSON

Ejemplo de respuesta JSON Lines

Ejemplo de respuesta Parquet

Campos de respuesta

Notas de uso

Códigos de error

Información de contacto