Preguntas frecuentes

Los créditos se cobran por lo que la API devuelve, no solo por las horas que pediste.

Credits = returned_valid_times * parameters * ceil(coordinates / 500)

returned_valid_times son los tiempos válidos que realmente vuelven por ubicación. En consultas de ensemble, cada miembro es su propia serie temporal.

• Los datasets subhorarios se cobran por tiempos válidos subhorarios devueltos.
• Los datasets con horizontes dispersos solo se cobran por los tiempos que devuelven.
• Los aciertos de caché se facturan al 10% de los créditos normales.

Puedes verificar uso y límites en tu panel del token.

Sí. Si necesitas hacer un backfill agresivo, podemos configurar ajustes temporales de cuota o capacidad para consumir más cuota en una ventana corta.

Escríbenos primero a info@gribstream.com con datasets, variables, rango de tiempo, cantidad de coordenadas y objetivo de finalización. Así podemos dimensionar la carga sin afectar capacidad compartida.

Un 429 suele indicar cuota agotada o burst throttling.

• Si agotaste cuota, Retry-After indica segundos hasta el próximo reset diario UTC.
• Si fue burst throttling, suele ser un cooldown corto.

Respeta Retry-After, usa exponential backoff con jitter y evita loops de reintentos.

Esto suele pasar cuando un cliente sigue reintentando solicitudes denegadas a alta frecuencia.

Para proteger capacidad compartida, GribStream puede aplicar bloqueos temporales a nivel IP. Normalmente duran de 10 minutos a 1 hora, según el patrón de tráfico.

Evítalo dejando de reintentar 401 hasta corregir la autenticación, respetando Retry-After en 429 y usando límites de reintentos.

Las cuotas diarias se reinician a las 00:00 UTC.

El contador exacto aparece en tu token dashboard.

Ambos endpoints consultan los mismos datos, pero responden preguntas distintas.

/timeseries

• Devuelve el mejor valor por tiempo válido: el menor lead time elegible según tus filtros.
• Es ideal para curvas de producto, dashboards, variables de modelado y backtesting basado en ejecuciones del modelo.
• Soporta asOf.

/runs

• Devuelve todos los valores por ejecución y horizonte que coinciden con el rango.
• Es mejor para comparar ciclos, estudiar deriva entre ejecuciones e investigación.
• Usa forecastedFrom/forecastedUntil, no asOf.

Usa fromTime/untilTime para ventanas densas y continuas. Usa timesList cuando ya conoces horarios exactos y necesitas una extracción dispersa.

En la práctica, timesList suele reducir descargas de más y créditos porque solo se devuelven los tiempos listados.

asOf es un corte por hora de ejecución del modelo para /timeseries: solo son elegibles las filas cuyo forecasted_at está en ese momento o antes.

Piensa en asOf como un corte desde el punto de vista de la hora de ejecución del modelo, no desde el momento en que GribStream indexó o expuso los datos.

Úsalo para backtesting basado en ejecuciones del modelo, evitando que ciclos posteriores entren en la consulta.

Si se omite asOf, GribStream usa las ejecuciones más recientes disponibles. /runs no usa asOf.

No. asOf usa la hora de ejecución del modelo, no la hora exacta en la que una ejecución quedó disponible en GribStream.

Por ejemplo, una ejecución GFS de 12Z puede ser elegible con asOf: "12:30Z" porque su forecasted_at es 12:00Z, aunque todavía no estuviera visible en la API a las 12:30Z.

Si necesitas aproximar la disponibilidad real de la API en un backtest, el flujo público estándar es aplicar un margen conservador antes de definir asOf. Parte de la hora histórica de decisión, resta una estimación del retraso habitual de publicación e indexación, y usa ese timestamp anterior como asOf.

Ese margen debería basarse en el retraso habitual entre el ciclo nominal del modelo y el momento en que el proveedor publica los horizontes relevantes en almacenamiento público de objetos/blob, con margen extra para retrasos ocasionales del proveedor o de GribStream. En feeds de NOAA como GFS, los archivos se suben en orden de horizonte de pronóstico, por lo que un flujo que solo usa las primeras 48 horas de pronóstico puede usar una corrección menor que otro que necesita la ejecución completa.

GribStream todavía no publica guías de retraso por dataset y horizonte en las páginas de modelo; esperamos resolverlo en una iteración separada. Puedes pedir includeMetadata: ["index_updated_at"] para ver el timestamp más reciente de las filas de índice usadas por cada resultado, pero no debe tratarse como un registro estable de primera disponibilidad. Puede haber flujos experimentales basados en la hora de indexación disponibles bajo solicitud, pero no forman parte del contrato estable de la API pública.

Las respuestas se transmiten en un orden optimizado para rendimiento, por lo que el orden cronológico no está garantizado.

Si necesitas un orden determinista, ordena los datos del lado del cliente después de descargarlos: en /timeseries por forecasted_time y luego forecasted_at; en /runs, por los campos de tiempo, ejecución y horizonte que use tu flujo.

Un selector de variable es un objeto JSON como:

{ "name": "TMP", "level": "2 m above ground", "info": "" }

• name: código de parámetro requerido, por ejemplo TMP o UGRD.
• level: nivel vertical o físico requerido.
• info: disambiguador opcional; requerido cuando varios campos comparten name + level.
• alias: nombre opcional para la columna de salida; no cambia la selección.

En cada página de modelo, el navegador de variables muestra el selector JSON exacto y permite copiarlo.

Normalmente significa que la grilla solicitada no intersecta el dominio del dataset.

• Los límites pueden estar fuera de la cobertura del modelo.
• Los límites de latitud/longitud pueden estar invertidos.
• La combinación de límites y step puede dejar cero puntos útiles tras filtrar por dominio.

Revisa la página del modelo, prueba primero una coordenada conocida dentro del dominio y luego escala a grilla.

En datasets de ensemble, usa el array members para elegir qué miembros devolver.

• Si members se omite, GribStream devuelve solo el primer miembro disponible, normalmente el miembro de control 0.
• Agregar miembros aumenta filas y créditos de forma casi lineal.
• Para descubrir miembros disponibles, consulta /api/v2/catalog/datasets/{dataset} e inspecciona members.

En datasets que no son ensemble, members no se usa.

En /timeseries, cada tiempo válido usa el valor de menor lead time elegible según tus filtros. Cerca de límites de ciclo, la ejecución seleccionada puede cambiar y eso puede crear saltos.

• Usa /runs si necesitas mantener una ejecución fija para toda la curva.
• Cuando exista, limita a horizonte 0 con minLeadTime: "0h" y maxLeadTime: "0h".
• Para visualizaciones intrahorarias, interpola entre puntos de referencia consecutivos de horizonte 0.

Para backfills grandes, optimiza un rendimiento estable y poca carga por punto devuelto.

• Divide el trabajo para que cada solicitud tarde unos 10 a 15 segundos.
• Maximiza coordenadas por solicitud mientras te mantengas en ese objetivo.
• Para horarios dispersos, usa timesList en vez de rangos amplios.
• Mantén las variables enfocadas; cada variable multiplica volumen y créditos.
• Haz una prueba pequeña antes de escalar.

Los aciertos de caché se facturan al 10% de los créditos normales y suelen responder mucho más rápido.

El caché ayuda sobre todo en datos consultados repetidamente: consultas recientes, valores tipo actual/horizonte corto y ventanas que clientes consultan con frecuencia.

• Las claves incluyen coordenadas, por lo que cambiar coordenadas suele cambiar la clave.
• Las solicitudes muy grandes de coordenadas no son elegibles para caché.
• Combinaciones antiguas o de horizonte alto suelen cachearse menos que consultas recientes y de horizonte corto.

Base recomendada:

• Authorization: Bearer <token>
• Content-Type: application/json
• Accept: text/csv, application/json o application/ndjson
• Accept-Encoding: gzip, muy recomendado para respuestas grandes

Asegúrate de que tu cliente acepte y descomprima gzip.

Usa expressions/filters en la API cuando puedas reducir el payload desde la solicitud: conversiones simples, umbrales, eventos y fórmulas directas.

Prefiere post-processing para lógica con estado, uniones entre datasets, enriquecimiento externo o pipelines más complejos.

Regla práctica: filtra y deriva en la API primero, luego aplica análisis avanzado más adelante.

Sí. GribStream soporta ambos flujos de trabajo en la misma API.

• Usa /timeseries con asOf para reconstruir el mejor pronóstico bajo un corte por hora de ejecución del modelo.
• Si necesitas aproximar la disponibilidad exacta en vivo, resta un margen conservador basado en el retraso habitual de publicación del proveedor para los horizontes que usas antes de definir asOf.
• Usa datasets de pronóstico como entradas y datasets de análisis u observaciones como objetivos de evaluación.
• Alinea por tiempo válido y coordenada; usa timesList cuando los horarios de evaluación son dispersos.

Ambas opciones son válidas, pero optimizan compromisos distintos.

• GRIB2 crudo: máximo control de bajo nivel, pero tú mantienes ingesta, indexación, decodificación, almacenamiento, reintentos y disponibilidad.
• GribStream API: pides solo variables, ubicaciones, tiempos y formatos necesarios, con menos carga operativa y una integración más rápida.

Muchos equipos usan un enfoque híbrido: API para producto y análisis, archivos crudos para investigación especializada.

Muchos modelos representan el viento con componentes u y v. Puedes calcular velocidad y dirección con:

speed = math.sqrt(u*u + v*v)
direction = (270 - math.atan2(v, u) * 180 / math.pi) % 360

u es la componente zonal oeste-este y v la componente meridional sur-norte. La segunda fórmula rota el ángulo a la convención meteorológica.

En GribStream puedes hacerlo con expressions como func.Hypot(uwind, vwind) y func.Atan2(vwind, uwind).

Convierte la temperatura de Kelvin a Celsius y aplica la aproximación Magnus-Tetens:

T_C = T - 273.15

a = 17.27
b = 237.7

gamma = (a * T_C) / (b + T_C) + math.log(RH / 100)
dew_point_C = (b * gamma) / (a - gamma)

También puedes calcularlo dentro de la respuesta usando GribStream expressions y devolver dew_point_C o dew_point_K como columnas derivadas.