hidrowebsdk

HidroWebSDK - SDK Python para a API Hidroweb da ANA

Este pacote fornece uma interface simples para se comunicar com a API Hidroweb da Agência Nacional de Águas (ANA) e acessar os dados hidrológicos disponíveis.

Adicionado na versão 0.2.1.

Exemplo

>>> from hidrowebsdk import Client
>>> client = Client()

class hidrowebsdk.Client(user='user', password='password', rate_limit=10)[código-fonte]

Base: object

Classe principal do cliente para interagir com a API Hidroweb da ANA.

Esta classe lida com a autenticação e fornece métodos para buscar vários tipos de dados da API Hidroweb, como informações de bacias, entidades e inventários de estações.

Atributos

userstr: O nome de usuário para autenticação da API.
passwordstr: A senha para autenticação da API.
clienthttpx.AsyncClient: O cliente HTTP usado para fazer solicitações.
tokenstr ou None: O token de autenticação obtido após o login.

async authenticate()[código-fonte]

Autentica com a API Hidroweb e obtém um token de acesso.

Este método envia uma solicitação GET para o endpoint OAuth com as credenciais do usuário para recuperar um token de autenticação, que é armazenado no cliente.

Exceções

Se a autenticação falhar ou nenhum token for retornado.

async bacias(codigo: int | None = None, last_update_start: datetime | None = None, last_update_end: datetime | None = None) → DataFrame[código-fonte]

Busca informações sobre bacias hidrológicas.

Parâmetros

codigoint, opcional: Código da bacia para filtrar resultados.
last_update_startdatetime, opcional: Data de início para filtro de última atualização.
last_update_enddatetime, opcional: Data de fim para filtro de última atualização.

Retorna

pd.DataFrame ou None: DataFrame contendo informações da bacia

async close()[código-fonte]

Fecha a sessão do cliente HTTP.

Este método deve ser chamado quando o cliente não for mais necessário para fechar adequadamente as conexões HTTP subjacentes.

async entidades(codigo: int | None = None, last_update_start: datetime | None = None, last_update_end: datetime | None = None) → DataFrame[código-fonte]

Busca informações sobre entidades.

Parâmetros

codigoint, opcional: Código da entidade para filtrar resultados.
last_update_startdatetime, opcional: Data de início para filtro de última atualização (aaaa-MM-dd).
last_update_enddatetime, opcional: Data de fim para filtro de última atualização (aaaa-MM-dd).

Retorna

pd.DataFrame: DataFrame contendo informações da entidade

Busca inventário de estações de monitoramento.

Parâmetros

codigoint, opcional: Código da estação para filtrar resultados.
last_update_startdatetime, opcional: Data de início para filtro de última atualização (aaaa-MM-dd).
last_update_enddatetime, opcional: Data de fim para filtro de última atualização (aaaa-MM-dd).
statestr, opcional: Estado (Unidade Federativa) para filtrar resultados.
basin_codeint, opcional: Código da bacia para filtrar resultados.

Retorna

pd.DataFrame ou None: DataFrame contendo inventário da estação.

async estacoes_hidrosat(codigo: str = '', last_update_start: datetime | None = None, last_update_end: datetime | None = None) → DataFrame[código-fonte]

Busca inventário de estações de monitoramento.

Parâmetros

codigostr, opcional: Código da estação para filtrar resultados.
last_update_startdatetime, opcional: Data de início para filtro de última atualização (aaaa-MM-dd).
last_update_enddatetime, opcional: Data de fim para filtro de última atualização (aaaa-MM-dd).

Retorna

pd.DataFrame: DataFrame contendo inventário da estação.

async estados(codigo: int | None = None, last_update_start: datetime | None = None, last_update_end: datetime | None = None) → DataFrame[código-fonte]

Busca informações sobre estados (Unidades Federativas).

Parâmetros

codigoint, opcional: Código do estado para filtrar resultados.
last_update_startdatetime, opcional: Data de início para filtro de última atualização.
last_update_enddatetime, opcional: Data de fim para filtro de última atualização.

Retorna

pd.DataFrame: DataFrame contendo informações dos estados.

async municipios(codigo: int | None = None, last_update_start: datetime | None = None, last_update_end: datetime | None = None) → DataFrame[código-fonte]

Busca informações sobre municípios.

Parâmetros

codigoint, opcional: Código do município para filtrar resultados.
last_update_startdatetime, opcional: Data de início para filtro de última atualização.
last_update_enddatetime, opcional: Data de fim para filtro de última atualização.

Retorna

pd.DataFrame ou None: DataFrame contendo informações do município

async rios(codigo: int | None = None, last_update_start: datetime | None = None, last_update_end: datetime | None = None) → DataFrame[código-fonte]

Busca informações sobre rios.

Parâmetros

codigoint, opcional: Código do rio para filtrar resultados.
last_update_startdatetime, opcional: Data de início para filtro de última atualização.
last_update_enddatetime, opcional: Data de fim para filtro de última atualização.

Retorna

pd.DataFrame ou None: DataFrame contendo informações do rio

async serie_chuva(codigo: int, start_datetime: datetime, end_datetime: datetime, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, ignore_time: bool = True) → DataFrame

Busca série histórica de dados de chuva para uma estação específica.

Parâmetros

codigoint: Código da estação para a qual buscar os dados.
start_datetimedatetime: Data e hora de início do intervalo para buscar os dados.
end_datetimedatetime: Data e hora de fim do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
ignore_timebool, opcional: Se True, ignora a parte do tempo e considera apenas a data. Nesse caso, a API considera a hora 00:00:00 para data inicial e 23:59:59 para data final.

Retorna

pd.DataFrame: DataFrame contendo a série histórica de dados de chuva.

async serie_cotas(codigo: int, start_datetime: datetime, end_datetime: datetime, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, ignore_time: bool = True) → DataFrame

Busca série histórica de dados de cotas para uma estação específica.

Parâmetros

codigoint: Código da estação para a qual buscar os dados.
start_datetimedatetime: Data e hora de início do intervalo para buscar os dados.
end_datetimedatetime: Data e hora de fim do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
ignore_timebool, opcional: Se True, ignora a parte do tempo e considera apenas a data. Nesse caso, a API considera a hora 00:00:00 para data inicial e 23:59:59 para data final.

Retorna

pd.DataFrame: DataFrame contendo a série histórica de dados de cotas.

async serie_curva_descarga(codigo: int, start_datetime: datetime, end_datetime: datetime, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, ignore_time: bool = True) → DataFrame

Busca série histórica de dados de curva de descarga para uma estação específica.

Parâmetros

codigoint: Código da estação para a qual buscar os dados.
start_datetimedatetime: Data e hora de início do intervalo para buscar os dados.
end_datetimedatetime: Data e hora de fim do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
ignore_timebool, opcional: Se True, ignora a parte do tempo e considera apenas a data. Nesse caso, a API considera a hora 00:00:00 para data inicial e 23:59:59 para data final.

Retorna

pd.DataFrame: DataFrame contendo a série histórica de dados de curva de descarga.

async serie_hidrosat(codigo: int, start_datetime: datetime, end_datetime: datetime, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, ignore_time: bool = True) → DataFrame

Busca série histórica de dados do Hidrosat para uma estação virtual específica.

Parâmetros

codigoint: Código da estação para a qual buscar os dados.
start_datetimedatetime: Data e hora de início do intervalo para buscar os dados.
end_datetimedatetime: Data e hora de fim do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
ignore_timebool, opcional: Se True, ignora a parte do tempo e considera apenas a data. Nesse caso, a API considera a hora 00:00:00 para data inicial e 23:59:59 para data final.

Retorna

pd.DataFrame: DataFrame contendo a série histórica de dados do Hidrosat.

async serie_perfil_transversal(codigo: int, start_datetime: datetime, end_datetime: datetime, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, ignore_time: bool = True) → DataFrame

Busca série histórica de dados de perfil transversal para uma estação específica.

Parâmetros

codigoint: Código da estação para a qual buscar os dados.
start_datetimedatetime: Data e hora de início do intervalo para buscar os dados.
end_datetimedatetime: Data e hora de fim do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
ignore_timebool, opcional: Se True, ignora a parte do tempo e considera apenas a data. Nesse caso, a API considera a hora 00:00:00 para data inicial e 23:59:59 para data final.

Retorna

pd.DataFrame: DataFrame contendo a série histórica de dados de perfil transversal.

async serie_qualidade_agua(codigo: int, start_datetime: datetime, end_datetime: datetime, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, ignore_time: bool = True) → DataFrame

Busca série histórica de dados de qualidade da água para uma estação específica.

Parâmetros

codigoint: Código da estação para a qual buscar os dados.
start_datetimedatetime: Data e hora de início do intervalo para buscar os dados.
end_datetimedatetime: Data e hora de fim do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
ignore_timebool, opcional: Se True, ignora a parte do tempo e considera apenas a data. Nesse caso, a API considera a hora 00:00:00 para data inicial e 23:59:59 para data final.

Retorna

pd.DataFrame: DataFrame contendo a série histórica de dados de qualidade da água.

async serie_resumo_descarga(codigo: int, start_datetime: datetime, end_datetime: datetime, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, ignore_time: bool = True) → DataFrame

Busca série histórica de dados de resumo de descarga para uma estação específica.

Parâmetros

codigoint: Código da estação para a qual buscar os dados.
start_datetimedatetime: Data e hora de início do intervalo para buscar os dados.
end_datetimedatetime: Data e hora de fim do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
ignore_timebool, opcional: Se True, ignora a parte do tempo e considera apenas a data. Nesse caso, a API considera a hora 00:00:00 para data inicial e 23:59:59 para data final.

Retorna

pd.DataFrame: DataFrame contendo a série histórica de dados de resumo de descarga.

async serie_sedimentos(codigo: int, start_datetime: datetime, end_datetime: datetime, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, ignore_time: bool = True) → DataFrame

Busca série histórica de dados de sedimentos para uma estação específica.

Parâmetros

codigoint: Código da estação para a qual buscar os dados.
start_datetimedatetime: Data e hora de início do intervalo para buscar os dados.
end_datetimedatetime: Data e hora de fim do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
ignore_timebool, opcional: Se True, ignora a parte do tempo e considera apenas a data. Nesse caso, a API considera a hora 00:00:00 para data inicial e 23:59:59 para data final.

Retorna

pd.DataFrame: DataFrame contendo a série histórica de dados de sedimentos.

async serie_telemetrica_adotada(codigo: int, end_datetime: datetime | None = None, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, range_filter: RangeFilter = RangeFilter.TWENTY_FOUR_HOURS) → DataFrame[código-fonte]

Busca série histórica adotada de dados telemétricos para uma estação específica(cota, nível e vazão).

Parâmetros

codigoint: Código da estação para a qual buscar os dados.
end_datetimedatetime: Data e hora de final do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
range_filterRangeFilter, opcional: Intervalo de busca termina no dia final (end_datetime) e inicia no dia final menos o intervalo. O padrão é o intevalo de um dia (RangeFilter.ONE_DAY), isto é, será buscado dados para o dia inteiro. O valor máximo permitido é de 30 dias (RangeFilter.THIRTY_DAYS) e o menor de 5 minutos (Rangefilter.FIVE_MINUTES).

Retorna

pd.DataFrame: DataFrame contendo a série histórica adotada de dados telemétricos.

async serie_telemetrica_adotada_multiplas_estacoes(codigos: list[int], end_datetime: datetime | None = None, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, range_filter: RangeFilter = RangeFilter.TWENTY_FOUR_HOURS) → DataFrame[código-fonte]

Busca série histórica detalhada de dados telemétricos para múltiplas estações específicas.

Parâmetros

codigoslist[int]: Lista de códigos das estações para as quais buscar os dados.
end_datetimedatetime: Data e hora de final do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
range_filterRangeFilter, opcional: Intervalo de busca termina no dia final (end_datetime) e inicia no dia final menos o intervalo. O padrão é o intevalo de um dia (RangeFilter.ONE_DAY), isto é, será buscado dados para o dia inteiro. O valor máximo permitido é de 30 dias (RangeFilter.THIRTY_DAYS) e o menor de 5 minutos (Rangefilter.FIVE_MINUTES).

Retorna

pd.DataFrame: DataFrame contendo a série histórica detalhada de dados telemétricos.

async serie_telemetrica_detalhada(codigo: int, end_datetime: datetime | None = None, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, range_filter: RangeFilter = RangeFilter.TWENTY_FOUR_HOURS) → DataFrame[código-fonte]

Busca série histórica detalhada de dados telemétricos para uma estação específica.

Parâmetros

codigoint: Código da estação para a qual buscar os dados.
end_datetimedatetime: Data e hora de final do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
range_filterRangeFilter, opcional: Intervalo de busca termina no dia final (end_datetime) e inicia no dia final menos o intervalo. O padrão é o intevalo de um dia (RangeFilter.ONE_DAY), isto é, será buscado dados para o dia inteiro. O valor máximo permitido é de 30 dias (RangeFilter.THIRTY_DAYS) e o menor de 5 minutos (Rangefilter.FIVE_MINUTES).

Retorna

pd.DataFrame: DataFrame contendo a série histórica detalhada de dados telemétricos.

async serie_telemetrica_detalhada_multiplas_estacoes(codigos: list[int], end_datetime: datetime | None = None, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, range_filter: RangeFilter = RangeFilter.TWENTY_FOUR_HOURS) → DataFrame[código-fonte]

Busca série histórica adotada de dados telemétricos para múltiplas estações específicas.

Parâmetros

codigoslist[int]: Lista de códigos das estações para as quais buscar os dados.
end_datetimedatetime: Data e hora de final do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
range_filterRangeFilter, opcional: Intervalo de busca termina no dia final (end_datetime) e inicia no dia final menos o intervalo. O padrão é o intevalo de um dia (RangeFilter.ONE_DAY), isto é, será buscado dados para o dia inteiro. O valor máximo permitido é de 30 dias (RangeFilter.THIRTY_DAYS) e o menor de 5 minutos (Rangefilter.FIVE_MINUTES).

Retorna

pd.DataFrame: DataFrame contendo a série histórica adotada de dados telemétricos.

async serie_vazao(codigo: int, start_datetime: datetime, end_datetime: datetime, date_filter: DateFilter = DateFilter.MEASUREMENT_DATE, ignore_time: bool = True) → DataFrame

Busca série histórica de dados de vazão para uma estação específica.

Parâmetros

codigoint: Código da estação para a qual buscar os dados.
start_datetimedatetime: Data e hora de início do intervalo para buscar os dados.
end_datetimedatetime: Data e hora de fim do intervalo para buscar os dados.
filter_typeDateFilter, opcional: Tipo de filtro de data a ser usado data da medição (FilterDate.MEASUREMENT_DATE) ou data da última atualização (FilterDate.LAST_UPDATE_DATE). Padrão para data da medição (FilterDate.MEASUREMENT_DATE).
ignore_timebool, opcional: Se True, ignora a parte do tempo e considera apenas a data. Nesse caso, a API considera a hora 00:00:00 para data inicial e 23:59:59 para data final.

Retorna

pd.DataFrame: DataFrame contendo a série histórica de dados de vazão.

async sub_bacias(codigo: int | None = None, last_update_start: datetime | None = None, last_update_end: datetime | None = None) → DataFrame[código-fonte]

Busca informações sobre sub-bacias hidrológicas.

Parâmetros

codigoint, opcional: Código da sub-bacia para filtrar resultados.
last_update_startdatetime, opcional: Data de início para filtro de última atualização.
last_update_enddatetime, opcional: Data de fim para filtro de última atualização.

Retorna

pd.DataFrame ou None: DataFrame contendo informações da sub-bacia

class hidrowebsdk.DateFilter(value)[código-fonte]

Base: Enum

LAST_UPDATE_DATE = 'DATA_ULTIMA_ATUALIZACAO'

MEASUREMENT_DATE = 'DATA_LEITURA'

class hidrowebsdk.RangeFilter(value)[código-fonte]

Base: Enum

EIGHTEEN_HOURS = 'HORA_18'

EIGHT_HOURS = 'HORA_8'

ELEVEN_HOURS = 'HORA_11'

FIFTEEN_HOURS = 'HORA_15'

FIFTEEN_MINUTES = 'MINUTO_15'

FIVE_HOURS = 'HORA_5'

FIVE_MINUTES = 'MINUTO_5'

FOURTEEN_DAYS = 'DIAS_14'

FOURTEEN_HOURS = 'HORA_14'

FOUR_HOURS = 'HORA_4'

NINETEEN_HOURS = 'HORA_19'

NINE_HOURS = 'HORA_9'

ONE_DAY = 'HORA_24'

ONE_HOUR = 'HORA_1'

SEVENTEEN_HOURS = 'HORA_17'

SEVEN_DAYS = 'DIAS_7'

SEVEN_HOURS = 'HORA_7'

SIXTEEN_HOURS = 'HORA_16'

SIX_HOURS = 'HORA_6'

TEN_HOURS = 'HORA_10'

TEN_MINUTES = 'MINUTO_10'

THIRTEEN_HOURS = 'HORA_13'

THIRTY_DAYS = 'DIAS_30'

THIRTY_MINUTES = 'MINUTO_30'

THREE_HOURS = 'HORA_3'

TWELVE_HOURS = 'HORA_12'

TWENTY_FOUR_HOURS = 'HORA_24'

TWENTY_HOURS = 'HORA_20'

TWENTY_ONE_DAYS = 'DIAS_21'

TWENTY_ONE_HOURS = 'HORA_21'

TWENTY_THREE_HOURS = 'HORA_23'

TWENTY_TWO_HOURS = 'HORA_22'

TWO_DAYS = 'DIAS_2'

TWO_HOURS = 'HORA_2'