Hydro-HUB | Documentação da API UNIPLU

Primeiros passos

O serviço fornece consultas públicas de leitura, sem chave de acesso. Os dados vêm do conjunto UNIPLU_BR no Hugging Face.

Cobertura instalada: 27 UFs · 2.885 combinações de estado e ano · anos de 1855 a 2025. A disponibilidade varia por estado e estação.

Endereço base

http://150.165.130.114

Encontre o código da estação em /api/stations?uf=PB&ano=2020. Use o campo gauge_code para consultar a precipitação.

Ver estações da Paraíba em 2020 ↗Exemplo de consulta com dez estações.

Monte sua consulta

Informe a UF e o código da estação. A série inclui todos os anos disponíveis.

Várias estações por área e período

Selecione um retângulo no mapa e informe as datas. A consulta reúne as estações dos estados dentro da área e permite baixar todas as medições do período em CSV.

Abrir consulta no mapa ↗

Rotas geográficas

/api/stations/area lista as estações. /api/precipitation/area retorna as medições.

Informe west, south, east, north, start e end. As coordenadas são longitude e latitude em graus. O JSON usa paginação; format=csv exporta todo o período.

Rotas disponíveis

Método e rota	O que retorna	Parâmetros obrigatórios
GET `/api/health`	Estado do serviço e quantidade de partições.	—
GET `/api/coverage`	Estados e anos disponíveis. Aceita filtro `uf`.	—
GET `/api/stations`	Estações, localização, rede e informações de horário.	`uf`, `ano`
GET `/api/precipitation`	Precipitação de uma estação em um único ano.	`uf`, `ano`, `gauge_code`
GET `/api/precipitation/series`	Série da estação em todos os anos, em JSON ou CSV.	`uf`, `gauge_code`

A documentação interativa mostra todos os parâmetros. O contrato da API está em OpenAPI JSON.

Série histórica completa

Consultar todos os anos em JSON

GET /api/precipitation/series?uf=AL&gauge_code=A303&limit=10000

Se has_more for true, faça a próxima consulta usando offset com o valor retornado em next_offset. Repita até has_more ser false.

Baixar todos os registros em CSV

GET /api/precipitation/series?uf=AL&gauge_code=A303&format=csv

O CSV inclui gauge_code, datetime, rain_mm e ano. Nesse formato, limit e offset não se aplicam.

Recortar um período entre anos

GET /api/precipitation/series?uf=AL&gauge_code=A303&start=2019-12-31T00:00:00&end=2020-01-02T23:59:59

Exemplo de download no terminal

curl "http://150.165.130.114/api/precipitation/series?uf=AL&gauge_code=A303&format=csv" -o A303.csv

“Série completa” significa todos os registros disponíveis na fonte. A API não preenche lacunas, não agrega os valores e não altera a resolução temporal.

Parâmetros de consulta

Parâmetro	Uso
`uf`	Sigla de duas letras maiúsculas, como `PB` ou `AL`.
`gauge_code`	Código da estação, retornado na rota de estações.
`ano`	Obrigatório nas consultas anuais; não é necessário na série completa.
`start` / `end`	Datas opcionais em formato ISO, sem indicação de fuso. Os limites são inclusivos.
`limit`	De 1 a 10.000 registros por página. Padrão: 100 para estações e 1.000 para precipitação.
`offset`	Quantidade de registros a pular, de 0 a 1.000.000. Padrão: 0.
`format`	`json` ou `csv`, somente na rota de série completa. Padrão: JSON.

A precipitação está em milímetros (rain_mm). Os horários seguem os valores armazenados na fonte; consulte o campo UTC da estação para interpretá-los. Valores ausentes são retornados como null no JSON e campos vazios no CSV.

Respostas e erros

Exemplo de resposta JSON da série

{
  "uf": "AL",
  "gauge_code": "A303",
  "scope": "all_years",
  "unit": "mm",
  "limit": 1,
  "offset": 0,
  "has_more": true,
  "next_offset": 1,
  "data": [{
    "gauge_code": "A303",
    "datetime": "2003-02-25T14:00:00",
    "rain_mm": 0.0,
    "ano": 2003
  }]
}

Exemplo ilustrativo de estrutura; consulte a API para obter os valores da fonte.

Código HTTP	Significado
`200`	Consulta concluída. Uma estação sem registros no período retorna uma lista vazia ou apenas o cabeçalho do CSV.
`404`	UF ou combinação de estado e ano sem dados.
`422`	Parâmetro inválido, ausente, ou datas em ordem incorreta.
`429`	Muitas consultas em sequência. Aguarde antes de tentar novamente.
`503`	Serviço ocupado. Tente novamente após alguns segundos.

O endereço atual usa HTTP. Não envie senhas ou informações privadas nas consultas.

Dados de precipitação.Acesso direto, por estação.