readNWISpeak: Peak flow data from USGS (NWIS)

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

Peak flow data from USGS (NWIS)

Description

Reads peak flow from NWISweb. Data is retrieved from https://waterdata.usgs.gov/nwis. In some cases, the specific date of the peak data is not know. This function will default to converting complete dates to a "Date" object, and converting incomplete dates to "NA". If those incomplete dates are needed, set the asDateTime argument to FALSE. No dates will be converted to R Date objects.

Usage

readNWISpeak(
  siteNumbers,
  startDate = "",
  endDate = "",
  asDateTime = TRUE,
  convertType = TRUE
)

Arguments

siteNumbers	character USGS site number(or multiple sites). This is usually an 8 digit number.
startDate	character starting date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates retrieval for the earliest possible record.
endDate	character ending date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates retrieval for the latest possible record.
asDateTime	logical default to TRUE. When TRUE, the peak_dt column is converted to a Date object, and incomplete dates are removed. When FALSE, no columns are removed, but no dates are converted.
convertType	logical, defaults to TRUE. If TRUE, the function will convert the data to dates, datetimes, numerics based on a standard algorithm. If false, everything is returned as a character

Value

A data frame with the following columns:

Name	Type	Description
agency_cd	character	The NWIS code for the agency reporting the data
site_no	character	The USGS site number
peak_dt	Date	Date of peak streamflow
peak_tm	character	Time of peak streamflow as character
peak_va	numeric	Annual peak streamflow value in cfs
peak_cd	character	Peak Discharge-Qualification codes (see comment for more information)
gage_ht	numeric	Gage height for the associated peak streamflow in feet
gage_ht_cd	character	Gage height qualification codes
year_last_pk	numeric	Peak streamflow reported is the highest since this year
ag_dt	Date	Date of maximum gage-height for water year (if not concurrent with peak)
ag_tm	character	Time of maximum gage-height for water year (if not concurrent with peak)
ag_gage_ht	numeric	maximum Gage height for water year in feet (if not concurrent with peak)
ag_gage_ht_cd	character	maximum Gage height code

There are also several useful attributes attached to the data frame:

Name	Type	Description
url	character	The url used to generate the data
queryTime	POSIXct	The time the data was returned
comment	character	Header comments from the RDB file
siteInfo	data.frame	A data frame containing information on the requested sites

See Also

constructNWISURL(), importRDB1()

Examples

site_ids <- c("01594440", "040851325")

data <- readNWISpeak(site_ids)
data2 <- readNWISpeak(site_ids, asDateTime = FALSE)
stations <- c("06011000")
peakdata <- readNWISpeak(stations, convertType = FALSE)

dataRetrieval documentation built on Aug. 8, 2025, 7:03 p.m.