Package 'hydrodownloadR'

Title: Hydrologic Station Catalogs and Time Series from Public APIs
Description: Provides a unified, extensible interface for discovering hydrological stations and downloading hydrological daily time series (e.g., water discharge, water level, water temperature) and discrete water-quality observations from national and regional public APIs. Water-quality observations are retained at their original sampling timestamps. Includes a provider registry, S3 generics 'stations' and 'timeseries', licensing metadata, date-range and 'complete history' modes, rate limiting and retries, optional authentication via environment variables, tidy outputs, UTF-8 to ASCII transliteration, and WGS84 coordinates. Designed for reproducible workflows and straightforward addition of new providers. Background and use cases are described in Farber et al. (2025) <doi:10.5194/essd-17-4613-2025> and Farber et al. (2023) <doi:10.57757/IUGG23-2838>.
Authors: Henning Plessow [aut, cre], Global Runoff Data Centre [ctb]
Maintainer: Henning Plessow <[email protected]>
License: MIT + file LICENSE
Version: 0.1.5
Built: 2026-10-14 11:21:30 UTC
Source: https://github.com/bafg-bund/hydrodownloadr

Help Index

Retrieve the complete BAFU NAWA Trend parameter catalogue

Description

The catalogue includes all physicochemical parameters, nutrients, micropollutants and the few hydrological parameters stored in NAWA. The parameter column shows how each provider parameter is handled by timeseries(). All entries classified as water_quality are returned together when parameter = "water_quality" is requested.

Usage

bafu_nawa_parameters(x, ...)

Arguments

x

A CH_BAFU_NAWA hydro service.
...

Unused.

Value

A tibble containing the provider's parameter catalogue.

SYKE runoff station metadata (area & altitude)

Description

Catchment area and altitude for Finnish SYKE runoff stations. Area may be NA for a few stations; altitude may still be present. Used to compute discharge from runoff time series: discharge_m3s = (value_lps_per_km2 * area_km2) / 1000.

Usage

data(fi_syke_runoff_meta)

Format

A tibble with:

place_id

Character. SYKE Paikka_Id.

area

Numeric (km^2). May be NA.

altitude

Numeric (m). May be NA.

Source

Finnish Environment Institute (SYKE).

FR_HUBEAU precomputed station metadata

Description

Preloaded metadata for Hub'Eau stations, built offline from the Hub'Eau referentials plus scraped site/station fiches (area, site altitude, gauge-zero altitude, vertical datum at site). Used to speed up stations() for the FR_HUBEAU provider.

Format

A data frame/tibble with columns:

code_site

Character. Hub'Eau site code.

station_id

Character. Hub'Eau station code.

area

Numeric (km2^2). Catchment area from site fiche; may be NA.

altitude_api

Numeric (m). API referential altitude (hydrometry in mm to m; temperature in m).

altitude_site

Numeric (m). Site altitude parsed from the site fiche; may be NA.

altitude_station

Numeric (m). "Cote du zero d'echelle" from station fiche; may be NA.

vertical_datum_site

Character. Site-level vertical datum label; may be NA.

retrieved_at

POSIXct (UTC). Timestamp when the row was scraped.

Details

Built by data-raw/fr_hubeau_meta_build.R. The file data/fr_hubeau_meta.rda is shipped with the package and may be refreshed out-of-band. A build-date string is also stored in the object attribute metadata_date.

Source

Hub'Eau APIs and https://www.hydro.eaufrance.fr/ site/station fiches.

Create a hydro service object

Description

Create a hydro service object

Usage

hydro_service(provider_id, ...)

Arguments

provider_id

ID as listed by hydro_services()
...

Reserved for future use.

Value

An object of class "hydro_service" (a list) containing the provider configuration used by stations() and timeseries() (e.g. provider_id, provider_name, country, base_url, and other adapter-specific settings).

List available providers

Description

List available providers

Usage

hydro_services()

Value

A tibble with columns: provider_id, provider_name, country, base_url, license, license_link, access_class, reuse_class, is_open_data

Japan MLIT stations metadata snapshot

Description

A processed station metadata table used internally by the JP MLIT adapter. Coordinates from the official MLIT station pages are preferred when available. Coordinates from the supplied metadata CSV are used as a fallback.

Usage

data(jp_mlit_meta)

Format

A tibble/data.frame with one row per station:

station_id

MLIT station identifier (character).

station_name

English station name (character).

river

English river-system name (character).

lat

Selected latitude in WGS84 decimal degrees (double).

lon

Selected longitude in WGS84 decimal degrees (double).

area

Drainage area in square kilometres, if available (double).

altitude

Gauge-zero elevation in metres, if available (double).

station_name_original

Original Japanese station name (character).

lat_website

Latitude obtained from the official MLIT station page (double).

lon_website

Longitude obtained from the official MLIT station page (double).

coordinate_source

Source used for lat and lon. Either "MLIT website" or "MLIT metadata CSV" (character).

Source

Japan Ministry of Land, Infrastructure, Transport and Tourism (MLIT).

List available countries

Description

List available countries

Usage

list_countries()

Value

A character vector of country codes (e.g. ISO 3166-1 alpha-2) for which at least one provider is available.

List stations for a provider

Description

List stations for a provider

Usage

stations(x, ...)

Arguments

x

A hydro_service object created by hydro_service().
...

Passed to provider-specific methods.

Value

A tibble with station metadata.

Examples

# Offline: enumerate providers (no network)
s <- hydro_services()
head(names(s))


# Online (opt-in): fetch stations
x <- hydro_service("SE_SMHI")
st <- stations(x)
head(st)

ANA stations (Brazil) - cache-first with optional update from inventory

Description

Loads the cached ANA station catalogue (if present) or rebuilds it from a locally downloaded SNIRH inventory (InventarioDD_MM_YYYY.zip / .mdb) when update = TRUE.

Usage

## S3 method for class 'hydro_service_BR_ANA'
stations(x, ...)

Arguments

x

A hydro_service created with hydro_service("BR_ANA").
...

Named arguments:

  • zip_or_mdb: path to InventarioDD_MM_YYYY.zip or .mdb

  • dest_dir: unzip destination (default: "data-raw/BR_ANA")

  • cache_dir: cache dir for RDS (default: user cache)

  • update: TRUE to rebuild from provided inventory

Value

A tibble with ANA station metadata.

Retrieve time series for a provider

Description

Retrieve time series for a provider

Usage

timeseries(
  x,
  parameter,
  stations = NULL,
  start_date = NULL,
  end_date = NULL,
  mode = c("range", "complete"),
  ...
)

Arguments

x

A hydro_service object created by hydro_service().
parameter

One of "water_discharge","water_level","water_temperature","water_velocity".
stations

Optional character vector of station IDs.
start_date, end_date

YYYY-MM-DD strings for mode = "range".
mode

Either "range" or "complete" (1900-01-01 to today).
...

Passed to provider-specific methods.

Value

A tibble with columns: country, provider_id, provider_name, station_id, parameter, timestamp, value, unit, quality_code, source_url.

Examples

# Offline: construct a service object (no network)
x <- hydro_service("SE_SMHI")


# Online (opt-in): one station for a short range
st <- head(stations(x)$station_id, 1)
ts <- timeseries(x, parameter = "water_discharge",
                 stations = st,
                 start_date = "2020-01-01", end_date = "2020-01-10")
head(ts)

List supported parameters/units for a provider

Description

List supported parameters/units for a provider

Usage

timeseries_parameters(x, ...)

Arguments

x

A hydro_service object.
...

Reserved for future use.

Value

A tibble with columns: parameter, code, unit.