RivRetrieve

RivRetrieve is an open-source Python package for finding and downloading river observations (discharge, stage and water temperature) directly from national and regional agencies around the world, through one consistent interface. RivRetrieve also ships a searchable catalogue of gauging stations, harmonises identifiers, units and columns across agencies, and records the source of every retrieval, so that results can be traced back to the original provider. The vision of RivRetrieve is to become a community platform for the world's openly published river data, one that grows as new agencies are added.

River data and where to find them

From floods to droughts: understanding and modelling rivers is a central environmental concern. For that, we need data. Preferably open data. Many countries measure their rivers at thousands of stations, but compiling that information is often hard. Different data portals, different languages, different formats. All of that adds up quickly for anyone interested in the data. The data exist, but accessing them is challenging.

RivRetrieve helps close this gap. It lets you find gauges, choose the physical observations you need, and retrieve them without learning a different Python interface for each agency. The map below shows countries where providers are already implemented and countries where data are coming soon. Currently, RivRetrieve retrieves observations from thirteen different providers in twelve countries.

Boundaries: Natural Earth. Their depiction implies no position on territorial status.

RivRetrieve focuses on time series of discharge, stage and water temperature. It leaves source quality judgements and study suitability to the reader. Think of RivRetrieve as a bridge between the original provider and the user.

Some providers require credentials. See the usage guide for how to supply them.

Know a data source we’re missing? Suggest it in a GitHub issue, with source links and relevant access information.

Install

Requires Python 3.13 or later. We recommend uv:

uv add rivretrieve

It also installs with pip: pip install rivretrieve.

For optional station maps, install the map extra: uv add "rivretrieve[map]".

Use with a coding agent

Copy the prompt below into your coding agent after installing RivRetrieve.

Use RivRetrieve to find and retrieve river discharge, stage, and water
temperature observations from national and regional agencies.

Check that rivretrieve imports in the project's Python environment and
note its version. If setup fails, report the error. Do not upgrade it
automatically.

Typical workflow:
import rivretrieve as rr

gauges = rr.find(
    provider="usgs_nwis", quantity="discharge",
    frequency="daily", statistic="mean",
)
selected = rr.pick(gauges, station=["07374000"])
result = rr.fetch(selected, start="2023-01-01", end="2023-01-01")

# Inspect observations, retrieval issues, and source-series outcomes.
result.data
result.issues
rr.series(result)

This illustrates the API; only retrieve data needed for the user's task.
Catalogue searches are offline; fetching contacts providers.

RivRetrieve harmonises units and structure. It does not perform quality
control, gap filling, or aggregation. Read timestamps with their time-zone
information. Returned rows do not imply complete coverage or no failures.

Consult documentation as needed:
- Usage, selections, results, credentials:
  https://rivretrieve.github.io/usage/
- Exact API signatures and returned types:
  https://rivretrieve.github.io/reference/
- Provider-specific access and interpretation:
  follow the relevant provider page from https://rivretrieve.github.io/

Continue the user's task without onboarding questions. If no task was
given, briefly confirm readiness.

Quick start

The packaged catalogue contains station locations and known source-series facts. Searching it does not contact the agencies. The following example then contacts USGS to retrieve one day of daily mean streamflow.

import rivretrieve as rr

# Find daily mean streamflow and choose a gauge.
daily_gauges = rr.find(
    provider="usgs_nwis", quantity="discharge", frequency="daily", statistic="mean"
)

chosen_gauges = rr.pick(daily_gauges, station=["07374000"])

result = rr.fetch(chosen_gauges, start="2023-01-01", end="2023-01-01")

# Inspect two columns as a short list of rows.
print(result.data.select("station_id", "value").rows())

# Output:
# [('07374000', 10562.183778816001)]

print(result.issues)

# Output:
# ()

The displayed values come from a recorded USGS response. Live source responses can change. The empty tuple means this retrieval reported no issues.

result.data is a Polars table of observations. Use rr.series(result) to inspect the returned source series and their outcomes. Discharge values use m³/s. Read timestamps together with their zone column. Inspect result.issues even when rows come back. A successful call does not establish continuous records or scientific comparability. Downloading observations requires internet access.

When an agency publishes different versions for the same variable

Brazil's ANA publishes bruto (raw) and consistido (quality-checked) daily records. ANA performs that checking, not RivRetrieve. Both are available. You choose whether to request both or just one. You can inspect and select them without credentials or network access:

brazil = rr.find(
    provider="br_ana", station="15400000", quantity="stage", frequency="daily", statistic="mean"
)

print(sorted(rr.series(brazil)["variant"].to_list()))

# Output:
# ['bruto', 'consistido']

consistido = rr.pick(brazil, variant="consistido")

print(rr.series(consistido)["variant"].to_list())

# Output:
# ['consistido']

Fetching brazil requests both daily mean water-level series by default. Fetching consistido requests only the quality-checked series. Not every period has observations for both. The usage guide shows the downloads and explains how to supply ANA credentials.

Next: the usage guide builds on the same example and covers selections, time windows, issues, credentials and caching. The CAMELS-US example retrieves streamflow for several gauges at once.

What RivRetrieve does and does not do

• Choose the observations you need. Search for discharge or narrow to daily means. A source appears in a daily-mean search only when its values are known to be daily means. Two matching records can still differ in ways that matter for your study.
• No quality control or gap filling. RivRetrieve does not assess scientific quality. It converts units and formats, and reports retrieval and parsing issues. Provider-specific observation quality flags are not added to harmonised output.
• No aggregation. RivRetrieve does not aggregate data (e.g., from hourly to daily). Data are returned at the time step the provider publishes: daily data are available only where the provider already publishes daily values.
• No hosting. RivRetrieve does not host or redistribute the data. Downloads come from the providers' own services.
• Fresh downloads depend on the providers. Service outages or changes can prevent new downloads. Previously cached observations can remain available.

Documentation

Start with the documentation index.

• Usage: selections, results, windows, issues, credentials, cache and receipts.
• Station metadata: names, coordinates, areas and elevations, and the field names each provider uses.
• Example: Recent streamflow for CAMELS-US gauges.
• Public API and software reference.
• Architecture: responsibilities, a traced request and contracts.

Data rights

Data rights remain with the original providers. The MIT licence in LICENSE applies to RivRetrieve's code, not to provider data, including packaged catalogues, station metadata and downloaded observations. Follow each provider's attribution, citation and reuse conditions. See station metadata rights and the provider pages.

Background

RivRetrieve is under active development. Breaking changes should be expected between release versions. See the issues for what is being worked on.

The package began as a Python translation of RivRetrieve for R by Ryan Riggs, made by Frederik Kratzert with the Gemini CLI and a few manual fixes for API changes. It has grown into a collaborative effort since, with Simon Moulds, Thiago Nascimento and Nicolas Lazaro.

Questions, bug reports and collaboration are welcome through the issues.

Acknowledgements

Importantly, this project would not exist without the open APIs of so many data providers. We thank them for their data and for supporting the philosophy of open data.

We also thank Henning Plessow at the Global Runoff Data Centre (GRDC) for the exchanges leading up to RivRetrieve’s first release. Their R package hydrodownloadR offers related access to station catalogues and daily time series from public national and regional APIs.