Série agregada por intervalo

GET

/stations/{stationId}/series

const url = 'https://api.radar-sandbox.kitelife.com.br/v1/stations/stn_barra-da-tijuca-01/series?from=2026-04-15T12%3A00%3A00Z&to=2026-04-15T12%3A00%3A00Z&resolution=10m';
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/series?from=2026-04-15T12%3A00%3A00Z&to=2026-04-15T12%3A00%3A00Z&resolution=10m' \
  --header 'X-Api-Key: <X-Api-Key>'

Agrega as leituras brutas em blocos de duração fixa, alinhados ao relógio. É a rota para gráficos, relatórios e qualquer período que passe de algumas horas.

resolution=10m reproduz o vento médio de 10 minutos, que é a convenção da Organização Meteorológica Mundial e o número que a maioria das aplicações náuticas espera ver.

Verifique sampleCount em cada bloco: um intervalo com poucas amostras indica que a estação teve lacunas, e a média daquele bloco é menos confiável que a dos vizinhos.

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

required

string format: date-time

resolution

required

string

Allowed values: 1m 10m 1h 1d

Duração de cada bloco. Cada resolução tem um teto de janela por requisição, para manter a resposta em tamanho razoável:

resolution	janela máxima
`1m`	7 dias
`10m`	90 dias
`1h`	1 ano
`1d`	5 anos

Example

10m

cursor

string

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

Responses

200

Página de blocos agregados, em ordem cronológica crescente.

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>

AggregatedReading

Resumo estatístico das leituras de uma estação dentro de um intervalo de tempo. É o formato da rota de série histórica, e a única forma prática de consultar períodos longos: a cadência bruta é de poucos segundos.

object

stationId

required

string

periodStart

required

Início do intervalo, inclusivo, em UTC. Os intervalos são alinhados ao relógio: resolution=10m começa em :00, :10, :20 e assim por diante.

string format: date-time

periodEnd

required

Fim do intervalo, exclusivo, em UTC.

string format: date-time

sampleCount

required

Quantidade de leituras brutas que compõem este intervalo. Compare com o esperado (duração ÷ reportingIntervalSeconds) para detectar lacunas: um intervalo de 10 minutos de uma estação de 8 segundos deveria conter cerca de 75 amostras.

integer

windSpeedKnotsAvg

Média aritmética da velocidade do vento no intervalo, em nós. Com resolution=10m este é o valor equivalente ao vento médio de 10 minutos da OMM.

number

windSpeedKnotsMin

number

windSpeedKnotsMax

number

windGustKnotsMax

Maior rajada registrada no intervalo, em nós.

number

windDirectionDegreesAvg

Direção média do vento no intervalo, calculada como média vetorial e não aritmética. A distinção importa: a média aritmética de 350° e 10° daria 180°, exatamente o oposto do vento real.

integer

<= 359

temperatureCelsiusAvg

number

temperatureCelsiusMin

number

temperatureCelsiusMax

number

humidityPercentAvg

number

pressureAbsoluteHpaAvg

Média da pressão medida na altitude da estação, em hectopascais.

number

pressureSeaLevelHpaAvg

Média da pressão reduzida ao nível do mar, em hectopascais. É a série a usar para tendência barométrica e para comparação entre estações. Ausente quando a altitude da estação não é conhecida.

number

rainMmTotal

Precipitação acumulada no intervalo, em milímetros. Diferente de Reading.rainRateMmPerHour, que é uma taxa instantânea: aqui a taxa já foi integrada ao longo do período.

number

uvIndexMax

number

Examples

doisBlocosDeDezMinutos

Dois blocos de 10 minutos

O primeiro bloco tem as 75 amostras esperadas de uma estação de 8 segundos. O segundo tem 41: houve lacuna, e a média daquele intervalo é menos confiável que a do vizinho.

{
  "data": [
    {
      "stationId": "stn_barra-da-tijuca-01",
      "periodStart": "2026-08-26T17:30:00Z",
      "periodEnd": "2026-08-26T17:40:00Z",
      "sampleCount": 75,
      "windSpeedKnotsAvg": 17.1,
      "windSpeedKnotsMin": 12.4,
      "windSpeedKnotsMax": 21,
      "windGustKnotsMax": 25.3,
      "windDirectionDegreesAvg": 114,
      "temperatureCelsiusAvg": 27.6,
      "temperatureCelsiusMin": 27.4,
      "temperatureCelsiusMax": 27.9,
      "humidityPercentAvg": 70.2,
      "pressureAbsoluteHpaAvg": 1012.5,
      "pressureSeaLevelHpaAvg": 1013,
      "rainMmTotal": 0,
      "uvIndexMax": 3.4
    },
    {
      "stationId": "stn_barra-da-tijuca-01",
      "periodStart": "2026-08-26T17:40:00Z",
      "periodEnd": "2026-08-26T17:50:00Z",
      "sampleCount": 41,
      "windSpeedKnotsAvg": 18,
      "windSpeedKnotsMin": 14.8,
      "windSpeedKnotsMax": 22.1,
      "windGustKnotsMax": 26,
      "windDirectionDegreesAvg": 117,
      "temperatureCelsiusAvg": 27.4,
      "temperatureCelsiusMin": 27.2,
      "temperatureCelsiusMax": 27.6,
      "humidityPercentAvg": 71,
      "pressureAbsoluteHpaAvg": 1012.4,
      "pressureSeaLevelHpaAvg": 1012.9,
      "rainMmTotal": 0,
      "uvIndexMax": 3.2
    }
  ]
}

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 maior que o teto da resolução pedida.

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