Reads current rating table for an active USGS streamgages. More information can be found at https://api.waterdata.usgs.gov/docs/stac/.
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_typeis "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. Iffile_typeis "exsa" then an additional column, SHIFT, is included that indicates the current shift in the rating for that value of INDEP. Iffile_typeis "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 isTRUE.
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.
Examples
# \donttest{
monitoring_location_id <- c("USGS-01104475", "USGS-01104460")
ratings_exsa <- read_waterdata_ratings(
monitoring_location_id = monitoring_location_id,
file_type = "exsa")
#> Remaining requests this hour:2073
#> Requesting:
#> https://api.waterdata.usgs.gov/stac-files/ratings/USGS.01104475.exsa.rdb
#> Requesting:
#> https://api.waterdata.usgs.gov/stac-files/ratings/USGS.01104460.exsa.rdb
head(ratings_exsa[["USGS-01104475.exsa.rdb"]])
#> INDEP SHIFT DEP STOR
#> 1 0.00 0.00 0 NA
#> 2 0.01 -0.01 0 NA
#> 3 0.02 -0.02 0 NA
#> 4 0.03 -0.03 0 NA
#> 5 0.04 -0.04 0 NA
#> 6 0.05 -0.05 0 NA
comment(ratings_exsa[["USGS-01104475.exsa.rdb"]])[1:15]
#> [1] "# //UNITED STATES GEOLOGICAL SURVEY http://water.usgs.gov/"
#> [2] "# //NATIONAL WATER INFORMATION SYSTEM http://water.usgs.gov/data.html"
#> [3] "# //DATA ARE PROVISIONAL AND SUBJECT TO CHANGE UNTIL PUBLISHED BY USGS"
#> [4] "# //RETRIEVED: 2026-02-03 19:23:31"
#> [5] "# //WARNING"
#> [6] "# //WARNING The stage-discharge rating provided in this file should be"
#> [7] "# //WARNING considered provisional and subject to change. Stage-discharge"
#> [8] "# //WARNING ratings change over time as the channel features that control"
#> [9] "# //WARNING the relation between stage and discharge vary. Users are"
#> [10] "# //WARNING cautioned to consider carefully the applicability of this"
#> [11] "# //WARNING rating before using it for decisions that concern personal or"
#> [12] "# //WARNING public safety or operational consequences."
#> [13] "# //FILE TYPE=\"NWIS RATING\" "
#> [14] "# //DATABASE NUMBER=01 DESCRIPTION=\" Standard data base for this site.\""
#> [15] "# //STATION AGENCY=\"USGS \" NUMBER=\"01104475 \" TIME_ZONE=\"EST\" DST_FLAG=Y"
ratings_corr <- read_waterdata_ratings(
monitoring_location_id = monitoring_location_id,
file_type = "corr")
#> Remaining requests this hour:2072
#> Requesting:
#> https://api.waterdata.usgs.gov/stac-files/ratings/USGS.01104475.corr.rdb
#> Requesting:
#> https://api.waterdata.usgs.gov/stac-files/ratings/USGS.01104460.corr.rdb
head(ratings_corr[["USGS-01104460.corr.rdb"]])
#> INDEP CORR CORRINDEP
#> 1 4.25 0.06 4.31
#> 2 4.26 0.06 4.32
#> 3 4.27 0.06 4.33
#> 4 4.28 0.06 4.34
#> 5 4.29 0.06 4.35
#> 6 4.30 0.06 4.36
comment(ratings_corr[["USGS-01104460.corr.rdb"]])[1:15]
#> [1] "# //UNITED STATES GEOLOGICAL SURVEY http://water.usgs.gov/"
#> [2] "# //NATIONAL WATER INFORMATION SYSTEM http://water.usgs.gov/data.html"
#> [3] "# //DATA ARE PROVISIONAL AND SUBJECT TO CHANGE UNTIL PUBLISHED BY USGS"
#> [4] "# //RETRIEVED: 2026-02-03 19:23:31"
#> [5] "# //WARNING"
#> [6] "# //WARNING The expanded stage-data corrections provided "
#> [7] "# //WARNING in this file should be considered provisional "
#> [8] "# //WARNING and subject to change. Stage corrections can "
#> [9] "# //WARNING change as adjustments are made to reference "
#> [10] "# //WARNING and recording gages following station levels "
#> [11] "# //WARNING and instrumentation resets. Users are "
#> [12] "# //WARNING cautioned to consider carefully the "
#> [13] "# //WARNING applicability of these corrections before "
#> [14] "# //WARNING using them for decisions that concern personal "
#> [15] "# //WARNING or public or operational consequences."
rating_2 <- read_waterdata_ratings(
monitoring_location_id = monitoring_location_id,
file_type = c("corr", "exsa"))
#> Remaining requests this hour:2073
#> Requesting:
#> https://api.waterdata.usgs.gov/stac-files/ratings/USGS.01104475.exsa.rdb
#> Requesting:
#> https://api.waterdata.usgs.gov/stac-files/ratings/USGS.01104475.corr.rdb
#> Requesting:
#> https://api.waterdata.usgs.gov/stac-files/ratings/USGS.01104460.exsa.rdb
#> Requesting:
#> https://api.waterdata.usgs.gov/stac-files/ratings/USGS.01104460.corr.rdb
names(rating_2)
#> [1] "USGS-01104475.exsa.rdb" "USGS-01104475.corr.rdb" "USGS-01104460.exsa.rdb"
#> [4] "USGS-01104460.corr.rdb"
bbox <- c(-95.00, 40.0, -92.0, 42)
bbox_query <- read_waterdata_ratings(bbox = bbox,
download_and_parse = FALSE)
#> Remaining requests this hour:2072
length(bbox_query)
#> [1] 177
recent_query <- read_waterdata_ratings(bbox = bbox,
datetime = c(Sys.Date()-7, NA),
download_and_parse = FALSE)
#> Remaining requests this hour:2071
length(recent_query)
#> [1] 87
# }