Author: Ryan M. Riggs and Simon Moulds
Date: 2026-08-21

# Introduction to the RivRetrieve R package

#### Ryan M. Riggs and Simon Moulds

#### August 21, 2026

## Here is a quick tutorial for RivRetrieve functions:

The `RivRetrieve` package is developed to efficiently access and download global river gauge data into an R environment. While numerous river data exists, our package is currently limited to daily measurements of river stage (meters) and discharge (cubic meters per second) for: Argentina, Australia, Brazil, Canada, Chile, France, Germany, Ireland, Japan, Quebec, Scotland, South Africa, the United Kingdom, and the United States.

    library(RivRetrieve)
    # Amazon River near Obidos, Brazil
    ## siteNumber='17050001'
    ## discharge=brazil(site=siteNumber,variable='discharge')
    ## stage=brazil(site=siteNumber,variable='stage')
    ## plot(discharge$Date,discharge$Q, type='l',xlab='',ylab='Discharge (cms)')

    # Mississippi River near Baton Rouge, LA, USA
    siteNumber="07374000"
    discharge=usa(site=siteNumber,variable='discharge')
    stage=usa(site=siteNumber,variable='stage')
    plot(discharge$Date,discharge$Q, type='l',xlab='',ylab='Discharge (cms)')

RivRetrieve automatically outputs a dataframe containing a `Date` column of `datetime` values and either a `H` or `Q` `numeric` column for the stage and discharge variable, respectively.

Stage is provided in meters and discharge is provided in cubic meters per second.

## Accessing the raw gauge data:

    library(knitr)
    ## kable(raw[1:5,],caption='Raw Brazilian gauge data')

    raw=original(discharge)
    kable(raw[1:5,],caption='Raw US gauge data')

Raw US gauge data
monitoring_location_id | parameter_code | statistic_id | time | value | unit_of_measure | approval_status | last_modified | qualifier | time_series_id
--- | --- | --- | --- | --- | --- | --- | --- | --- | ---
USGS-07374000 | 00060 | 00003 | 2004-03-17 | 726000 | ft^3/s | Approved | 2025-06-06 03:55:20 |  | c9d823a2491f4b639656a11b35a7625d
USGS-07374000 | 00060 | 00003 | 2004-03-18 | 752000 | ft^3/s | Approved | 2025-06-06 03:55:20 |  | c9d823a2491f4b639656a11b35a7625d
USGS-07374000 | 00060 | 00003 | 2004-03-19 | 769000 | ft^3/s | Approved | 2025-06-06 03:55:20 |  | c9d823a2491f4b639656a11b35a7625d
USGS-07374000 | 00060 | 00003 | 2004-03-20 | 786000 | ft^3/s | Approved | 2025-06-06 03:55:20 |  | c9d823a2491f4b639656a11b35a7625d
USGS-07374000 | 00060 | 00003 | 2004-03-21 | 799000 | ft^3/s | Approved | 2025-06-06 03:55:20 |  | c9d823a2491f4b639656a11b35a7625d

## Site locations for all agencies can also be found:

    ## brazilSites=brazil(sites=TRUE)
    ## kable(brazilSites[1:10,],caption='Example Brazilian river gauge locations')

    usaSites=usa(sites=TRUE)
    kable(usaSites[1:10,],caption='Example US river gauge locations')

Example US river gauge locations
site | latitude | longitude
--- | --- | ---
02479500 | 30.86241 | -88.41779
02480020 | 30.63936 | -88.39307
02479960 | 30.78713 | -88.36696
02479431 | 31.16101 | -88.36196
02479955 | 30.80852 | -88.33668
02480000 | 30.72936 | -88.33612
02479945 | 30.85602 | -88.33390
02468000 | 32.43347 | -88.33336
02479980 | 30.78019 | -88.31890
02479950 | 30.81130 | -88.31584

## Date defined retrieval

Specific time periods can also be accessed if the entire time series is not needed.

    # Annual timeseries
    ## siteNumber='17050001'
    ## recent=brazil(site=siteNumber,variable='stage',start_date = start,end_date = end)
    ## plot(recent$Date,recent$H,type='l', xlab='',ylab='Stage (m)')

    siteNumber="07374000"
    start='2009-01-01'
    end='2010-01-31'
    recent=usa(site=siteNumber,variable='stage',start_date = start,end_date = end)
    plot(recent$Date,recent$H,type='l', xlab='',ylab='Stage (m)')