Surface-water measurement data retrieval from USGS (NWIS)

Reads surface-water measurement data from NWISweb. Data is retrieved from https://waterdata.usgs.gov/nwis. See https://waterdata.usgs.gov/usa/nwis/sw for details about surface water.

Usage

readNWISmeas(
  siteNumbers,
  startDate = "",
  endDate = "",
  tz = "UTC",
  expanded = FALSE,
  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.

tz

character to set timezone attribute of dateTime. Default is "UTC", and converts the date times to UTC, properly accounting for daylight savings times based on the data's provided tz_cd column. Possible values to provide are "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", "America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also OlsonNames() for more information on time zones.

expanded

logical. Whether or not (TRUE or FALSE) to call the expanded data.

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 at least 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
measurement_dt	POSIXct	The date and time (in POSIXct) of the measurement. Unless specified with the tz parameter, this is converted to UTC. If the measurement_dt column is an incomplete, a measurement_dt_date and measurement_dt_time column are added to the returned data frame.
tz_cd	character	The time zone code for the measurement_dt column

See https://waterdata.usgs.gov/usa/nwis/sw for details about surface water, and https://waterdata.usgs.gov/nwis/help?output_formats_help for help on the columns and codes.

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
tz_cd_reported	The originally reported time zone

See also

constructNWISURL, importRDB1

Examples

site_ids <- c("01594440", "040851325")
# \donttest{
data <- readNWISmeas(site_ids)
#> GET: https://waterdata.usgs.gov/nwis/measurements/?site_no=01594440,040851325&range_selection=date_range&format=rdb
Meas05316840 <- readNWISmeas("05316840")
#> GET: https://waterdata.usgs.gov/nwis/measurements/?site_no=05316840&range_selection=date_range&format=rdb
Meas05316840.ex <- readNWISmeas("05316840", expanded = TRUE)
#> GET: https://waterdata.usgs.gov/nwis/measurements/?site_no=05316840&range_selection=date_range&format=rdb_expanded
Meas07227500.ex <- readNWISmeas("07227500", expanded = TRUE)
#> GET: https://waterdata.usgs.gov/nwis/measurements/?site_no=07227500&range_selection=date_range&format=rdb_expanded
Meas07227500.exRaw <- readNWISmeas("07227500", expanded = TRUE, convertType = FALSE)
#> GET: https://waterdata.usgs.gov/nwis/measurements/?site_no=07227500&range_selection=date_range&format=rdb_expanded
# }