Leituras brutas em um intervalo

GET

/stations/{stationId}/readings

const url = 'https://api.radar-sandbox.kitelife.com.br/v1/stations/stn_barra-da-tijuca-01/readings?from=2026-08-26T12%3A00%3A00Z&to=2026-08-26T13%3A00%3A00Z&limit=100';
const options = {method: 'GET', headers: {'X-Api-Key': '<X-Api-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.radar-sandbox.kitelife.com.br/v1/stations/stn_barra-da-tijuca-01/readings?from=2026-08-26T12%3A00%3A00Z&to=2026-08-26T13%3A00%3A00Z&limit=100' \
  --header 'X-Api-Key: <X-Api-Key>'

Devolve as leituras exatamente como a estação as publicou, sem agregação.

A janela é limitada a 24 horas por requisição. Não é uma restrição arbitrária: a cadência de uma estação é de poucos segundos, então um único dia já são milhares de pontos. Para períodos maiores use /stations/{stationId}/series, que agrega antes de transmitir.

O dado bruto tem retenção menor que a série agregada. Antes de construir um arquivo histórico em cima desta rota, confira a política de retenção no guia de mesmo nome.

Authorizations

ApiKey

Parameters

Path Parameters

stationId

required

string

Identificador público da estação.

Example

stn_barra-da-tijuca-01

Query Parameters

from

required

string format: date-time

Início da janela, inclusivo. UTC, ISO 8601.

Example

2026-08-26T12:00:00Z

required

string format: date-time

Fim da janela, exclusivo. No máximo 24 h após from.

Example

2026-08-26T13:00:00Z

cursor

string

Cursor opaco devolvido em nextCursor. Omita para a primeira página.

limit

integer

default: 100 >= 1 <= 1000

Itens por página nas rotas de série temporal.

Responses

200

Página de leituras, em ordem cronológica crescente de observedAt.

application/json

object

data

required

Itens desta página, em ordem cronológica crescente.

array

nextCursor

Cursor opaco da próxima página. Ausente quando não há mais dados no intervalo pedido. Devolva-o em ?cursor= sem interpretá-lo: o formato é interno e muda sem aviso.

string

data

required

Array<object>

Reading

Uma leitura meteorológica de uma estação, em um instante. Este é o objeto canônico do produto: o mesmo corpo é retornado pela API REST, empurrado pelo WebSocket e entregue pelo relay AMQP. Toda grandeza carrega a unidade no próprio nome do campo, vento em nós é o padrão náutico do produto e a fonte de erro mais provável para quem integra.

object

stationId

required

Identificador público e estável da estação. É desvinculado do hardware: trocar o equipamento de uma estação não altera este valor.

string

observedAt

required

Instante da medição, sempre UTC com sufixo Z. É a chave temporal de toda série histórica e, junto de stationId, a chave de deduplicação.

string format: date-time

timeSource

Confiabilidade do horário em observedAt.

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

reconstructed: a estação estava sem relógio no momento da medição, e a plataforma datou a leitura a partir de outra leitura da mesma sessão que tinha hora. A precisão fica na ordem de segundos, suficiente para série temporal, insuficiente para correlacionar com eventos externos ao segundo exato.

unanchored: sem relógio e sem nenhuma referência de hora na sessão inteira. observedAt vem como LIMITE SUPERIOR: a medição ocorreu em algum momento antes desse instante, por uma duração desconhecida. O que se preserva é a ORDEM entre leituras, não a data. Se o seu uso depende de quando exatamente algo aconteceu, descarte estes pontos.

Uma estação sem relógio não deixa de medir, e a leitura nunca é descartada por falta de hora, daí este campo existir.

string

default: station

Allowed values: station reconstructed unanchored

receivedAt

Instante em que a plataforma recebeu a leitura. Difere de observedAt quando a estação ficou sem link e retransmitiu depois. Serve para medir atraso, nunca para ordenar a série.

string format: date-time

windSpeedKnots

required

Velocidade média do vento, em nós. Medida pelo sensor no intervalo de amostragem, não é a média móvel de 10 minutos. Para essa, consulte a rota de histórico com resolution=10m.

number

windGustKnots

Maior rajada observada no intervalo de amostragem, em nós. Reportada pelo próprio sensor. Ausente quando a estação não reporta esta grandeza; ver Station.measurements.

number

windDirectionDegrees

required

Direção de onde o vento sopra, em graus verdadeiros. 0 = norte, 90 = leste. Não há correção de alinhamento de mastro aplicada.

integer

<= 359

temperatureCelsius

Temperatura do ar, em graus Celsius. Ausente quando a estação não reporta esta grandeza; ver Station.measurements.

number

humidityPercent

Umidade relativa do ar, em porcentagem. Ausente quando a estação não reporta esta grandeza; ver Station.measurements.

integer

<= 100

pressureAbsoluteHpa

Pressão atmosférica medida na altitude da estação, em hectopascais. NÃO é reduzida ao nível do mar. Duas estações em altitudes diferentes mostram valores diferentes sob o mesmo tempo, e a diferença é altitude, não descalibração. Para comparar estações entre si, use pressureSeaLevelHpa.

number

pressureSeaLevelHpa

Pressão reduzida ao nível do mar (QNH), em hectopascais. É o valor comparável entre estações e o que sustenta leitura de tendência barométrica ao longo da costa. Derivado pela plataforma a partir da pressão absoluta, da altitude e da temperatura da estação: ausente quando a altitude da estação não é conhecida.

number

rainRateMmPerHour

Taxa de precipitação instantânea, em milímetros por hora. É uma taxa, não um acumulado: integrá-la ao longo do tempo é responsabilidade de quem consome. Ausente quando a estação não reporta esta grandeza; ver Station.measurements.

number

uvIndex

Índice UV, adimensional. Ausente quando a estação não reporta esta grandeza; ver Station.measurements.

number

Examples

doisPontos

Duas leituras consecutivas, com o intervalo de 8 s da estação

{
  "data": [
    {
      "stationId": "stn_barra-da-tijuca-01",
      "observedAt": "2026-08-26T17:42:00Z",
      "timeSource": "station",
      "receivedAt": "2026-08-26T17:42:01Z",
      "windSpeedKnots": 17.6,
      "windGustKnots": 22.9,
      "windDirectionDegrees": 115,
      "temperatureCelsius": 27.5,
      "humidityPercent": 70,
      "pressureAbsoluteHpa": 1012.4,
      "pressureSeaLevelHpa": 1012.9,
      "rainRateMmPerHour": 0,
      "uvIndex": 3.2
    },
    {
      "stationId": "stn_barra-da-tijuca-01",
      "observedAt": "2026-08-26T17:42:08Z",
      "timeSource": "station",
      "receivedAt": "2026-08-26T17:42:09Z",
      "windSpeedKnots": 18.2,
      "windGustKnots": 24.6,
      "windDirectionDegrees": 118,
      "temperatureCelsius": 27.4,
      "humidityPercent": 71,
      "pressureAbsoluteHpa": 1012.4,
      "pressureSeaLevelHpa": 1012.9,
      "rainRateMmPerHour": 0,
      "uvIndex": 3.1
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0wOC0yNlQxNzo0MjowOFoifQ"
}

401

Chave ausente, inválida ou revogada.

application/problem+json

Problem

Corpo de erro conforme RFC 9457 (Problem Details for HTTP APIs). Toda resposta 4xx e 5xx da API usa este formato, com Content-Type application/problem+json. O código de negócio viaja na extensão code, no formato Recurso.Motivo.

object

type

required

URI que identifica o tipo do erro. Estável: é nele que o integrador deve programar, nunca no texto de title.

string format: uri

title

required

Resumo legível do tipo do erro.

string

status

required

integer

>= 100 <= 599

detail

Explicação específica desta ocorrência.

string

instance

string format: uri-reference

traceId

Identificador da requisição. Cite-o ao abrir um chamado de suporte.

string

errors

Presente apenas em 422: erros de validação agrupados por campo.

object

key

additional properties

Array<string>

code

Código de negócio no formato Recurso.Motivo. É o valor a usar em lógica condicional quando o type não for específico o bastante. Presente em erros de regra de negócio; ausente em falhas genéricas de protocolo.

string

Example

{
  "type": "https://docs.radar.kitelife.com.br/errors/unauthorized",
  "title": "Credencial inválida",
  "status": 401,
  "code": "ApiKey.NotRecognized",
  "detail": "A chave enviada em X-Api-Key não foi reconhecida."
}

404

Estação inexistente ou fora do escopo da sua chave.

application/problem+json

Problem

object

type

required

URI que identifica o tipo do erro. Estável: é nele que o integrador deve programar, nunca no texto de title.

string format: uri

title

required

Resumo legível do tipo do erro.

string

status

required

integer

>= 100 <= 599

detail

Explicação específica desta ocorrência.

string

instance

string format: uri-reference

traceId

Identificador da requisição. Cite-o ao abrir um chamado de suporte.

string

errors

Presente apenas em 422: erros de validação agrupados por campo.

object

key

additional properties

Array<string>

code

string

Example

{
  "type": "https://docs.radar.kitelife.com.br/errors/station-not-found",
  "title": "Estação não encontrada",
  "status": 404,
  "code": "Station.NotFound",
  "detail": "Nenhuma estação com id stn_inexistente-99."
}

422

Janela inválida: to anterior a from, ou intervalo maior que 24 h.

application/problem+json

Problem

object

type

required

URI que identifica o tipo do erro. Estável: é nele que o integrador deve programar, nunca no texto de title.

string format: uri

title

required

Resumo legível do tipo do erro.

string

status

required

integer

>= 100 <= 599

detail

Explicação específica desta ocorrência.

string

instance

string format: uri-reference

traceId

Identificador da requisição. Cite-o ao abrir um chamado de suporte.

string

errors

Presente apenas em 422: erros de validação agrupados por campo.

object

key

additional properties

Array<string>

code

string

Example

{
  "type": "https://docs.radar.kitelife.com.br/errors/station-not-found",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "code": "Station.NotFound"
}

429

Cota excedida. O cabeçalho Retry-After traz os segundos a esperar. Repetir antes disso não adianta e conta contra você.

application/problem+json

Problem

object

type

required

URI que identifica o tipo do erro. Estável: é nele que o integrador deve programar, nunca no texto de title.

string format: uri

title

required

Resumo legível do tipo do erro.

string

status

required

integer

>= 100 <= 599

detail

Explicação específica desta ocorrência.

string

instance

string format: uri-reference

traceId

Identificador da requisição. Cite-o ao abrir um chamado de suporte.

string

errors

Presente apenas em 422: erros de validação agrupados por campo.

object

key

additional properties

Array<string>

code

string

Example

{
  "type": "https://docs.radar.kitelife.com.br/errors/station-not-found",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "code": "Station.NotFound"
}

Headers

Retry-After

integer