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 time series.

• 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 cache hits se facturan al 10% de los créditos normales.

Puedes verificar uso y límites en tu token dashboard.

Sí. Si necesitas hacer un backfill agresivo, podemos configurar ajustes temporales de cuota o throughput 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 requests denegados 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 un mejor valor por tiempo válido: el menor lead time disponible bajo tus filtros.
• Es ideal para curvas de producto, dashboards, features y backtesting sin leakage.
• Soporta asOf.

/runs

• Devuelve todos los valores run/horizon que coinciden con el rango.
• Es mejor para comparar ciclos, estudiar drift entre runs e investigación.
• Usa forecastedFrom/forecastedUntil, no asOf.

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

En la práctica, timesList suele reducir over-fetching y créditos porque solo se devuelven los tiempos listados.

asOf es un timestamp de corte para /timeseries: solo son elegibles los runs producidos en ese momento o antes.

Úsalo para backtesting sin leakage, es decir, para reconstruir qué se sabía en ese momento sin incorporar runs futuros.

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

Las responses se streamen en un orden optimizado para throughput, por lo que el orden cronológico no está garantizado.

Si necesitas orden determinista, ordena client-side después de descargar: en /timeseries por forecasted_time y luego forecasted_at; en /runs, por los campos de tiempo y run/horizon que use tu workflow.

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 browser de variables muestra el selector JSON exacto y permite copiarlo.

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

• Los bounds pueden estar fuera de la cobertura del modelo.
• Los límites de latitud/longitud pueden estar invertidos.
• La combinación de bounds 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 grid.

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 disponible bajo tus filtros. Cerca de límites de ciclo, el run seleccionado puede cambiar y eso puede crear saltos.

• Usa /runs si necesitas mantener un run fijo para toda la curva.
• Cuando exista, limita a horizonte 0 con minLeadTime: "0h" y maxLeadTime: "0h".
• Para visualizaciones intrahorarias, interpola entre anchors consecutivos de horizonte 0.

Para backfills grandes, optimiza throughput estable y bajo overhead por punto devuelto.

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

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

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

• Las keys incluyen coordenadas, por lo que cambiar coordenadas suele cambiar la key.
• Requests muy grandes de coordenadas no son elegibles para cache.
• Combinaciones antiguas o de horizonte alto suelen cachearse menos que consultas recientes y de horizonte corto.

Baseline recomendado:

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

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

Usa expressions/filters en la API cuando puedas reducir payload temprano: conversiones simples, thresholds, eventos y fórmulas directas.

Prefiere post-processing para lógica stateful, joins cross-dataset, enriquecimiento externo o pipelines más complejos.

Default práctico: filtra y deriva en la API primero, luego aplica analytics avanzados downstream.

Sí. GribStream soporta ambos workflows en la misma API.

• Usa /timeseries con asOf para reconstruir qué pronóstico estaba disponible en cada timestamp histórico.
• Usa datasets de forecast como inputs y datasets de análisis/actuales como targets de evaluación.
• Alinea por tiempo válido y coordenada; usa timesList cuando los timestamps de evaluación son dispersos.

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

• GRIB2 crudo: máximo control de bajo nivel, pero tú mantienes ingest, indexación, decoding, storage, retries y disponibilidad.
• GribStream API: pides solo variables, ubicaciones, tiempos y formatos necesarios, con menos overhead operativo y una integración más rápida.

Muchos equipos usan un enfoque híbrido: API para producto y analytics, 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 response usando GribStream expressions y devolver dew_point_C o dew_point_K como columnas derivadas.