Perguntas frequentes

Os créditos são cobrados pelo que a API realmente retorna, não apenas pelas horas solicitadas.

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

returned_valid_times são os horários válidos retornados por local. Em consultas de ensemble, cada membro gera sua própria série temporal.

• Datasets infra-horários são cobrados pelos horários válidos infra-horários retornados.
• Datasets com horizontes esparsos são cobrados apenas pelos horários que retornam.
• Cache hits são cobrados a 10% dos créditos normais.

Sim. Para um backfill grande, podemos configurar ajustes temporários de cota ou throughput (vazão) para consumir mais cota em uma janela curta.

Entre em contato em info@gribstream.com com datasets, variáveis, intervalo de tempo, quantidade de coordenadas e prazo desejado.

Um 429 normalmente indica cota esgotada ou limitação de rajada.

• Se a cota acabou, Retry-After indica quantos segundos faltam para o próximo reset diário em UTC.
• Se foi limitação de rajada, geralmente é uma pausa curta.

Respeite Retry-After, use backoff exponencial com jitter e evite loops de retry muito agressivos.

Isso costuma acontecer quando um cliente continua tentando requisições negadas em alta frequência. Para proteger a capacidade compartilhada, o GribStream pode bloquear temporariamente o IP de origem.

Evite isso corrigindo a autenticação antes de repetir 401, respeitando Retry-After em 429 e limitando novas tentativas.

As cotas diárias reiniciam às 00:00 UTC. A contagem exata aparece no dashboard do seu token em /app/dashboard.

/timeseries retorna o melhor valor elegível por horário válido, com o menor lead time (horizonte de previsão) permitido pelos seus filtros. É ideal para curvas de produto, dashboards, variáveis de modelagem e backtesting baseado em execuções do modelo.

/runs retorna todos os valores correspondentes por execução do modelo e horizonte. Use para comparar ciclos, analisar desvio entre execuções ou fazer pesquisa.

Use fromTime/untilTime para janelas densas e contínuas. Use timesList quando já souber os horários exatos e precisar de uma extração esparsa.

asOf define um corte pelo horário de execução do modelo em /timeseries: apenas linhas cujo forecasted_at está nesse horário ou antes são elegíveis.

Pense nele do ponto de vista do horário de execução do modelo, não como o momento em que o GribStream indexou ou expôs os dados.

Use em backtesting baseado em execuções do modelo, sem deixar ciclos posteriores entrarem na consulta.

Não. asOf usa o horário de execução do modelo, não o horário exato em que uma execução ficou disponível no GribStream.

Por exemplo, uma execução GFS 12Z pode ser elegível com asOf: "12:30Z" porque seu forecasted_at é 12:00Z, mesmo que ainda não estivesse visível na API às 12:30Z.

Se você precisa aproximar a disponibilidade real da API em um backtest, o fluxo público padrão é aplicar uma margem conservadora antes de definir asOf. Comece pelo horário histórico de decisão, subtraia uma estimativa do atraso usual de publicação e indexação, e use esse timestamp anterior como asOf.

Essa margem deve se basear no atraso usual entre o ciclo nominal do modelo e o momento em que o provedor publica os horizontes relevantes em armazenamento público de objetos/blob, com margem extra para atrasos ocasionais do provedor ou do GribStream. Em feeds NOAA como GFS, os arquivos são enviados em ordem de horizonte de previsão, então um fluxo que usa só as primeiras 48 horas de previsão costuma poder usar uma correção menor que outro que precisa da execução completa.

O GribStream ainda não publica guias de atraso por dataset e horizonte nas páginas dos modelos; esperamos tratar isso em uma iteração separada. Você pode solicitar includeMetadata: ["index_updated_at"] para ver o timestamp mais recente das linhas de índice usadas por cada resultado, mas isso não deve ser tratado como um registro estável de primeira disponibilidade. Fluxos experimentais baseados no horário de indexação podem estar disponíveis mediante solicitação, mas não fazem parte do contrato público estável da API.

As respostas são transmitidas em uma ordem otimizada para vazão. Se precisar de ordem determinística, ordene do lado do cliente depois de baixar os dados.

Um seletor é um objeto JSON exato como { "name": "TMP", "level": "2 m above ground", "info": "" }. Copie name, level e info da página do modelo; eles não são rótulos para traduzir.

A grade solicitada provavelmente não cruza o domínio do dataset. Confira a cobertura do modelo, os limites de latitude/longitude e o step, e teste uma coordenada conhecida dentro do domínio.

Para datasets de ensemble, use o campo members. Se omitido, o GribStream retorna apenas o primeiro membro disponível, normalmente o membro de controle 0. Adicionar membros aumenta linhas e créditos quase linearmente.

Em /timeseries, cada horário válido usa o menor lead time elegível. Quando a execução de origem muda perto de um limite de ciclo, a série pode mostrar saltos. Use /runs para manter uma execução fixa do modelo.

Para backfills grandes, mantenha requisições limitadas e previsíveis: mire cerca de 10 a 15 segundos por requisição, maximize coordenadas dentro desse alvo, use timesList para horários esparsos, mantenha poucas variáveis e faça um teste pequeno antes de escalar.

Cache hits custam 10% dos créditos normais e geralmente são mais rápidos. O cache ajuda mais em requisições repetidas recentes ou de baixo lead time. Mudar coordenadas normalmente muda a chave de cache, e requisições com muitas coordenadas não são elegíveis.

Base recomendada:

• Authorization: Bearer <token>
• Content-Type: application/json
• Accept: text/csv, application/json ou application/ndjson
• Accept-Encoding: gzip para respostas grandes

Use expressions e filtros na API quando eles reduzem o payload logo na requisição: conversões de unidade, limiares, filtros de eventos e fórmulas simples. Use pós-processamento para lógica com estado, joins entre datasets, enriquecimento externo ou pipelines complexos.

Sim. Use /timeseries com asOf para reconstruir a melhor previsão sob um corte pelo horário de execução do modelo. Se precisar aproximar a disponibilidade exata na API ao vivo, subtraia antes de definir asOf uma margem conservadora baseada no atraso usual de publicação do provedor para os horizontes usados. Depois combine datasets de previsão com datasets de análise ou observações como alvos de avaliação, e use timesList quando os horários de avaliação forem esparsos.

GRIB2 bruto dá controle máximo no nível dos arquivos, mas você opera ingestão, indexação, decodificação, armazenamento, novas tentativas e disponibilidade. A API do GribStream retorna apenas as variáveis, locais, tempos e formatos necessários, com muito menos trabalho operacional.

Muitos modelos codificam vento com componentes u e v. Calcule velocidade e direção meteorológica com:

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

Em GribStream expressions, use func.Hypot(uwind, vwind) e func.Atan2(vwind, uwind).

Converta a temperatura de Kelvin para Celsius e aplique a aproximação 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)

Você pode retornar dew_point_C ou dew_point_K como colunas derivadas com GribStream expressions.