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.
Value
List of named lists, one per requested rating file. Each element contains:
- ratings
Data frame of the rating curve.
- metadata
Data frame of header/value pairs parsed from the comment attribute of the ratings file.
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")
#> Requesting:
#> https://api.waterdata.usgs.gov/stac/v0/search?filter=monitoring_location_id%20IN%20%28%27USGS-01104475%27%2C%20%27USGS-01104460%27%29%20AND%20file_type%20%3D%20%27exsa%27&limit=10000&f=json&lang=en-US
#> Remaining requests this hour:2638
#> 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"]]$ratings)
#> 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
m1 <- ratings_exsa[["USGS-01104475.exsa.rdb"]]$metadata
m1
#> $WARNING
#> [1] "The stage-discharge rating provided in this file should be considered provisional and subject to change. Stage-discharge ratings change over time as the channel features that control the relation between stage and discharge vary. Users are cautioned to consider carefully the applicability of this rating before using it for decisions that concern personal or public safety or operational consequences."
#>
#> $`Comment 1`
#> [1] "UNITED STATES GEOLOGICAL SURVEY http://water.usgs.gov/"
#>
#> $`Comment 2`
#> [1] "NATIONAL WATER INFORMATION SYSTEM http://water.usgs.gov/data.html"
#>
#> $`Comment 3`
#> [1] "DATA ARE PROVISIONAL AND SUBJECT TO CHANGE UNTIL PUBLISHED BY USGS"
#>
#> $`Comment 4`
#> [1] "RETRIEVED : 2026-07-10 19:35:01"
#>
#> $FILE
#> [1] "NWIS RATING"
#>
#> $DATABASE
#> NUMBER DESCRIPTION
#> 1 01 Standard data base for this site.
#>
#> $STATION
#> AGENCY NUMBER TIME_ZONE DST_FLAG
#> 1 USGS 01104475 EST Y
#> NAME
#> 1 STONY BROOK RES., UNNAMED TRIB 1, NEAR WESTON, MA
#>
#> $LABEL
#> [1] "\"Discharge (ft^3/s)\""
#>
#> $PARAMETER
#> [1] "00060"
#>
#> $RATING
#> SHIFTED ID TYPE NAME AGING
#> 1 20260710193501 EST 1 STGQ stage-discharge ????
#> REMARKS EXPANSION
#> 1 STANDARD 120 DEGREE WEIR FORMULA standardequation
#>
#> $RATING_INDEP
#> ROUNDING PARAMETER
#> 1 ???? Gage height (ft)
#>
#> $RATING_DEP
#> ROUNDING PARAMETER
#> 1 ???? Discharge (ft^3/s)
#>
#> $RATING_DATETIME
#> BEGIN BZONE END EZONE AGING
#> 1 20031201000001 -05:00 20161206000000 -05:00 1
#> 2 20161206000000 -05:00 -------------- --- 1
#> COMMENT
#> 1 STANDARD 120 DEGREE WEIR FORMULA
#> 2 STANDARD 120 DEGREE WEIR FORMULA
#>
#> $SHIFT_NEXT
#> BEGIN BZONE END EZONE STAGE1 SHIFT1 STAGE2 SHIFT2 STAGE3
#> 1 -------------- --- -------------- --- --- --- --- --- ---
#> SHIFT3 COMMENT
#> 1 ---
#>
ratings_corr <- read_waterdata_ratings(
monitoring_location_id = monitoring_location_id,
file_type = "corr")
#> Requesting:
#> https://api.waterdata.usgs.gov/stac/v0/search?filter=monitoring_location_id%20IN%20%28%27USGS-01104475%27%2C%20%27USGS-01104460%27%29%20AND%20file_type%20%3D%20%27corr%27&limit=10000&f=json&lang=en-US
#> Remaining requests this hour:2638
#> 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"]]$ratings)
#> INDEP CORR CORRINDEP
#> 1 4.25 0 4.25
#> 2 4.26 0 4.26
#> 3 4.27 0 4.27
#> 4 4.28 0 4.28
#> 5 4.29 0 4.29
#> 6 4.30 0 4.30
m2 <- ratings_corr[["USGS-01104460.corr.rdb"]]$metadata
m2
#> $WARNING
#> [1] "The expanded stage-data corrections provided in this file should be considered provisional and subject to change. Stage corrections can change as adjustments are made to reference and recording gages following station levels and instrumentation resets. Users are cautioned to consider carefully the applicability of these corrections before using them for decisions that concern personal or public or operational consequences."
#>
#> $`Comment 1`
#> [1] "UNITED STATES GEOLOGICAL SURVEY http://water.usgs.gov/"
#>
#> $`Comment 2`
#> [1] "NATIONAL WATER INFORMATION SYSTEM http://water.usgs.gov/data.html"
#>
#> $`Comment 3`
#> [1] "DATA ARE PROVISIONAL AND SUBJECT TO CHANGE UNTIL PUBLISHED BY USGS"
#>
#> $`Comment 4`
#> [1] "RETRIEVED : 2026-07-09 19:30:02"
#>
#> $FILE
#> [1] "EXPANDED STAGE DATA CORRECTIONS (MODIFIED NWIS PRODUCT)"
#>
#> $DATABASE
#> NUMBER DESCRIPTION
#> 1 01 Standard data base for this site.
#>
#> $STATION
#> AGENCY NUMBER TIME_ZONE DST_FLAG NAME
#> 1 USGS 01104460 EST Y STONY BROOK AT RT 20 AT WALTHAM, MA
#>
#> $LABEL
#> [1] "\"Gage height (ft)\""
#>
#> $PARAMETER
#> [1] "00060"
#>
#> $RATING
#> [1] "6"
#>
#> $CORR1_PREV
#> BEGIN BZONE END EZONE STAGE1 CORR1 STAGE2 CORR2 STAGE3
#> 1 -------------- --- -------------- --- --- --- --- --- ---
#> CORR3 COMMENT
#> 1 ---
#>
#> $CORR1_NEXT
#> BEGIN BZONE END EZONE STAGE1 CORR1 STAGE2 CORR2 STAGE3
#> 1 -------------- --- -------------- --- --- --- --- --- ---
#> CORR3 COMMENT
#> 1 ---
#>
#> $CORR2_PREV
#> BEGIN BZONE END EZONE STAGE1 CORR1 STAGE2 CORR2 STAGE3
#> 1 -------------- --- -------------- --- --- --- --- --- ---
#> CORR3 COMMENT
#> 1 ---
#>
#> $CORR2_NEXT
#> BEGIN BZONE END EZONE STAGE1 CORR1 STAGE2 CORR2 STAGE3
#> 1 -------------- --- -------------- --- --- --- --- --- ---
#> CORR3 COMMENT
#> 1 ---
#>
#> $CORR3_PREV
#> BEGIN BZONE END EZONE STAGE1 CORR1 STAGE2 CORR2 STAGE3
#> 1 -------------- --- -------------- --- --- --- --- --- ---
#> CORR3 COMMENT
#> 1 ---
#>
#> $CORR3_NEXT
#> BEGIN BZONE END EZONE STAGE1 CORR1 STAGE2 CORR2 STAGE3
#> 1 -------------- --- -------------- --- --- --- --- --- ---
#> CORR3 COMMENT
#> 1 ---
#>
rating_2 <- read_waterdata_ratings(
monitoring_location_id = monitoring_location_id,
file_type = c("corr", "exsa"))
#> Requesting:
#> https://api.waterdata.usgs.gov/stac/v0/search?filter=monitoring_location_id%20IN%20%28%27USGS-01104475%27%2C%20%27USGS-01104460%27%29&limit=10000&f=json&lang=en-US
#> Remaining requests this hour:2638
#> 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"
m3 <- rating_2$`USGS-01104460.exsa.rdb`$metadata
rat_data <- rating_2$`USGS-01104460.exsa.rdb`$ratings
bbox <- c(-95.00, 40.0, -92.0, 42)
bbox_query <- read_waterdata_ratings(bbox = bbox,
download_and_parse = FALSE)
#> Requesting:
#> https://api.waterdata.usgs.gov/stac/v0/search?bbox=-95%2C40%2C-92%2C42&limit=10000&f=json&lang=en-US
#> Remaining requests this hour:2636
length(bbox_query)
#> [1] 177
recent_query <- read_waterdata_ratings(bbox = bbox,
datetime = c(Sys.Date()-7, NA),
download_and_parse = FALSE)
#> Requesting:
#> https://api.waterdata.usgs.gov/stac/v0/search?datetime=2026-07-09T00%3A00%3A00Z%2F..&bbox=-95%2C40%2C-92%2C42&limit=10000&f=json&lang=en-US
#> Remaining requests this hour:2635
# }