read_waterdata_ratings: Get USGS Rating Curve Data

In dataRetrieval: Retrieval Functions for USGS and EPA Hydrology and Water Quality Data

Get USGS Rating Curve Data

Description

Reads current rating table for an active USGS streamgages. More information can be found at https://api.waterdata.usgs.gov/docs/stac/.

Usage

read_waterdata_ratings(
  monitoring_location_id = NA_character_,
  file_type = c("exsa", "base", "corr"),
  file_path = tempdir(),
  bbox = NA,
  datetime = NA_character_,
  ...,
  limit = 10000,
  download_and_parse = TRUE
)

Arguments

monitoring_location_id	A unique identifier representing a single monitoring location. Monitoring location IDs are created by combining the agency code of the agency responsible for the monitoring location (e.g. USGS) with the ID number of the monitoring location (e.g. 02238500), separated by a hyphen (e.g. USGS-02238500).
file_type	Rating file time. Could be any of "exsa", "corr", or "base". If file_type is "base" then the columns are INDEP, typically the gage height, in feet; DEP, typically the streamflow, in cubic feet per second; and STOR, where "*" indicates that the pair are a fixed point of the rating curve. If file_type is "exsa" then an additional column, SHIFT, is included that indicates the current shift in the rating for that value of INDEP. If file_type is "corr" then the columns are INDEP, typically the gage height, in feet; CORR, the correction for that value; and CORRINDEP, the corrected value for CORR.
file_path	Path to save the rating curve rdb files. The default is tempdir(), which will wipe out the files.
bbox	Only features that have a geometry that intersects the bounding box are selected.The bounding box is provided as four or six numbers, depending on whether the coordinate reference system includes a vertical axis (height or depth). Coordinates are assumed to be in crs 4326. The expected format is a numeric vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).
datetime	Only return items that have a temporal property that intersects this value. Either a date-time or an interval, open or closed. See Details below.
...	Not used.
limit	Limits the number of results that are included in each page of the response (capped at the default 10,000).
download_and_parse	Logical to define whether or not to download, parse, and return a list of data frames with rating curve data (TRUE), or to return just a list of available rating curve files (FALSE). Default is TRUE.

Details

You can also use a vector of length 2 for any time queries (such as time or last_modified). The first value is the starting date (or datetime), the second value is the ending date(or datetime). NA's within the vector indicate a half-bound date. For example, time = c("2024-01-01", NA) will return all data starting at 2024-01-01. time = c(NA, "2024-01-01") will return all data from the beginning of the timeseries until 2024-01-01. By default, time is assumed UTC, although time zone attributes will be accommodated. As an example, setting time = as.POSIXct(c("2021-01-01 12:00:00", "2021-01-01 14:00"), tz = "America/New_York") will request data that between noon and 2pm eastern time on 2021-01-01. All time values RETURNED from the service are UTC with the exception of daily data, which returns time values in local dates.

Value

List of data frames which contain the requested rating curves.

Examples

monitoring_location_id <- c("USGS-01104475", "USGS-01104460")
ratings_exsa <- read_waterdata_ratings(
      monitoring_location_id = monitoring_location_id,
      file_type = "exsa")

head(ratings_exsa[["USGS-01104475.exsa.rdb"]])
comment(ratings_exsa[["USGS-01104475.exsa.rdb"]])[1:15]

ratings_corr <- read_waterdata_ratings(
      monitoring_location_id = monitoring_location_id,
      file_type = "corr")

head(ratings_corr[["USGS-01104460.corr.rdb"]])
comment(ratings_corr[["USGS-01104460.corr.rdb"]])[1:15]

rating_2 <- read_waterdata_ratings(
      monitoring_location_id = monitoring_location_id,
      file_type = c("corr", "exsa"))
names(rating_2)

bbox <- c(-95.00, 40.0, -92.0, 42)

bbox_query <- read_waterdata_ratings(bbox = bbox,
                                     download_and_parse = FALSE)
length(bbox_query)
recent_query <- read_waterdata_ratings(bbox = bbox,
                                       datetime = c(Sys.Date()-7, NA),
                                       download_and_parse = FALSE)
length(recent_query)

dataRetrieval documentation built on May 28, 2026, 9:06 a.m.