Grandezas e unidades

A fonte mais comum de erro numa API meteorológica não é o protocolo, é a unidade. Um cliente que lê windSpeedKnots como se fosse metro por segundo mostra 18 quando o vento real é 35, e nada no sistema acusa o engano.

Por isso toda grandeza carrega a unidade no nome do campo.

Vento

Campo	Unidade	Observação
windSpeedKnots	nós (kn)	Velocidade média no intervalo de amostragem
windGustKnots	nós (kn)	Maior rajada no mesmo intervalo
windDirectionDegrees	graus verdadeiros, 0 a 359	Direção de onde o vento sopra

Nó, não metro por segundo. A conversão para nós acontece na própria estação, antes da publicação. É a unidade do público do produto: vela, kite, náutica em geral. Para converter, 1 kn ≈ 0,514 m/s ≈ 1,852 km/h.

Direção é de onde vem. Vento de 90° é vento de leste, soprando para oeste. É a convenção meteorológica, e é o contrário do que se espera de um vetor de deslocamento.

Nenhuma correção de alinhamento é aplicada. Se o mastro foi instalado desalinhado, o desvio aparece no dado.

O vento é medido na altura daquele mastro

windSpeedKnots é o valor medido onde o anemômetro está, sem normalização de altura. A altura de cada estação está em Station.location.anemometerHeightMeters.

Isso importa em dois usos comuns, e nos dois o viés é sistemático, não é ruído que some na média:

• Comparar duas estações. Vento a 6 m e vento a 12 m não são o mesmo número sob o mesmo tempo. A diferença é a altura, e ninguém vai atribuí-la a isso.
• Comparar com previsão. Modelos meteorológicos entregam vento a 10 m, que é a referência da Organização Meteorológica Mundial. Confrontar a estação com a previsão sem corrigir a altura produz uma divergência constante que parece erro do modelo.

Precisando comparar, corrija pela altura antes.

Média de 10 minutos

windSpeedKnots é a média do intervalo de amostragem da estação, de poucos segundos. Não é a média móvel de dez minutos que a Organização Meteorológica Mundial adota como referência e que a maioria das aplicações náuticas espera.

Para o valor de 10 minutos, use a rota de série com resolution=10m. O campo windSpeedKnotsAvg do bloco agregado é o equivalente.

Direção média não é média aritmética

Ao agregar direção, a plataforma usa média vetorial. A distinção não é preciosismo: a média aritmética entre 350° e 10° dá 180°, apontando exatamente para o lado oposto do vento real. Se você agregar direção por conta própria, decomponha em seno e cosseno antes de somar.

Atmosfera

Campo	Unidade	Observação
temperatureCelsius	°C	Temperatura do ar
humidityPercent	%	Umidade relativa, 0 a 100
pressureAbsoluteHpa	hPa	Medida na altitude da estação
pressureSeaLevelHpa	hPa	Reduzida ao nível do mar (QNH)
rainRateMmPerHour	mm/h	Taxa instantânea, não acumulado
uvIndex	adimensional	Índice UV

Existem duas pressões, e escolher a errada estraga a comparação.

pressureAbsoluteHpa é o que o sensor mediu, na altitude onde ele está. Duas estações em altitudes diferentes mostram valores diferentes sob exatamente o mesmo tempo, e quem não souber disso vai concluir que uma delas está descalibrada.

pressureSeaLevelHpa é o mesmo valor reduzido ao nível do mar, derivado pela plataforma a partir da altitude e da temperatura da estação. É esta a série a usar para comparar estações e para ler tendência barométrica ao longo da costa, que é o uso que antecipa virada de vento.

O campo reduzido fica ausente quando a altitude da estação não é conhecida (Station.location.elevationMeters). Sem altitude não há como reduzir.

Chuva é taxa, não volume. rainRateMmPerHour responde “com que intensidade está chovendo agora”, não “quanto choveu”. Para o acumulado, use rainMmTotal no bloco agregado da série: lá a taxa já foi integrada no período.

Tempo

Todo instante é UTC, em ISO 8601 com sufixo Z. O fuso local da estação está em Station.timezone, para apresentação.

Campo	Significado
observedAt	Quando o fenômeno foi medido. É a chave temporal da série
receivedAt	Quando a plataforma recebeu o dado
timeSource	Quanto se pode confiar em observedAt

receivedAt pode estar bem depois de observedAt: uma estação que ficou sem link acumula leituras e as envia quando volta. Use observedAt para ordenar e para posicionar no gráfico; receivedAt serve para medir atraso de entrega, e só.

Os três níveis de confiança do horário

O relógio da estação vem do provisionamento. Num reinício longe disso, ela mede sem saber que horas são, e continua medindo: a leitura nunca é descartada por falta de hora. timeSource diz o que aconteceu.

station é o horário carimbado pela estação, com relógio válido. É o caso normal, e o único em que observedAt é exato.

reconstructed significa que a estação estava sem relógio e a plataforma datou a leitura a partir de outra da mesma sessão que tinha hora. Precisão na ordem de segundos: serve para série temporal, não serve para correlacionar com um evento externo ao segundo exato.

Não é caso raro. Toda estação nova passa por ele, porque o relógio só chega no provisionamento e tudo que ela mediu antes disso é datado depois, para trás.

unanchored significa sem relógio e sem nenhuma referência de hora na sessão inteira. observedAt vem como limite superior: a medição aconteceu em algum momento antes desse instante, por uma duração desconhecida.

O que sobrevive num lote unanchored é a ordem, não a data. As leituras estão na sequência correta entre si. Se o seu uso é uma série ordenada, elas servem; se depende de quando exatamente algo aconteceu, descarte-as.

Campos ausentes

Um campo que a estação não reporta é omitido do JSON, nunca enviado como null. Para saber de antemão o que esperar de cada estação, consulte Station.measurements: o que não estiver nessa lista nunca virá.

Lacuna na série tem outro significado. Se um intervalo de tempo simplesmente não tem leitura, houve falha de sensor, de link ou de energia. Não há valor “aproximado” preenchendo buraco.