Brazil Fetcher

Fetcher for Brazilian river gauge data from ANA Hidroweb.

class rivretrieve.brazil.BrazilFetcher(username: str | None = None, password: str | None = None)[source]

Bases: RiverDataFetcher

Fetches river gauge data from Brazil’s National Water and Sanitation Agency (ANA).

Data Source: ANA Hidroweb API v2 (https://www.ana.gov.br/hidroweb/) Requires credentials (username/password) which can be set in a .env file in the rivretrieve directory or passed to the constructor. Keys in .env: ANA_USERNAME, ANA_PASSWORD

Supported Variables:

  • 'discharge_daily_mean' (m³/s)

  • 'stage_daily_mean' (m)

static get_available_variables() → tuple[str, ...][source]

Returns a tuple of supported variables.

static get_cached_metadata() → DataFrame[source]

Retrieves a DataFrame of available Brazilian gauge IDs and metadata.

This method loads the metadata from a cached CSV file located in the rivretrieve/cached_site_data/ directory.

Returns:

A DataFrame indexed by gauge_id, containing site metadata.

Return type:

pd.DataFrame

get_data(gauge_id: str, variable: str, start_date: str | None = None, end_date: str | None = None) → DataFrame[source]

Fetches and parses time series data for a specific gauge and variable.

This method retrieves the requested data from the provider’s API or data source, parses it, and returns it in a standardized pandas DataFrame format.

Parameters:

  • gauge_id – The site-specific identifier for the gauge.

  • variable – The variable to fetch. Must be one of the strings listed in the fetcher’s get_available_variables() output. These are typically defined in rivretrieve.constants.

  • start_date – Optional start date for the data retrieval in ‘YYYY-MM-DD’ format. If None, data is fetched from the earliest available date.

  • end_date – Optional end date for the data retrieval in ‘YYYY-MM-DD’ format. If None, data is fetched up to the latest available date.

Returns:

A pandas DataFrame indexed by datetime objects ('time') with a single column named after the requested variable. The DataFrame will be empty if no data is found for the given parameters.

Return type:

pd.DataFrame

Raises:

  • ValueError – If the requested variable is not supported by this fetcher.

  • requests.exceptions.RequestException – If a network error occurs during data download.

  • Exception – For other unexpected errors during data fetching or parsing.

get_metadata() → DataFrame[source]

Fetches station metadata for all Brazilian states from the ANA Hidroweb API.

Data is fetched from the HidroInventarioEstacoes endpoint: https://www.ana.gov.br/hidrowebservice/EstacoesTelemetricas/HidroInventarioEstacoes/v1

Returns:

A DataFrame indexed by gauge_id, containing site metadata.

Return type:

pd.DataFrame