dataRetrieval: readNWISgwl – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

readNWISgwl

Groundwater level measurements retrieval from USGS (NWIS)

Description

Reads groundwater level measurements from NWISweb. Mixed date/times come back from the service depending on the year that the data was collected. See https://waterdata.usgs.gov/usa/nwis/gw for details about groundwater. By default the returned dates are converted to date objects, unless convertType is specified as FALSE. Sites with non-standard date formats (i.e. lacking a day) can be affected (see examples). See https://waterservices.usgs.gov/rest/GW-Levels-Service.html for more information.

Usage

readNWISgwl(
  siteNumbers,
  startDate = "",
  endDate = "",
  parameterCd = NA,
  convertType = TRUE,
  tz = "UTC"
)

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.
`parameterCd`	character USGS parameter code. This is usually an 5 digit number. Default is "".
`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
`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.

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
site_tp_cd	character	Site type code
lev_dt	Date	Date level measured
lev_tm	character	Time level measured
lev_tz_cd	character	Time datum
lev_va	numeric	Water level value in feet below land surface
sl_lev_va	numeric	Water level value in feet above specific vertical datum
lev_status_cd	character	The status of the site at the time the water level was measured
lev_agency_cd	character	The agency code of the person measuring the water level

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

Examples

site_id <- "434400121275801"

data <- readNWISgwl(site_id)
sites <- c("434400121275801", "375907091432201")
data2 <- readNWISgwl(site_id, '','')
data3 <- readNWISgwl("420125073193001", '','')
#handling of data where date has no day
data4 <- readNWISgwl("425957088141001", startDate = "1980-01-01") 

data5 <- readNWISgwl("263819081585801", parameterCd = "72019")

dataRetrieval

Retrieval Functions for USGS and EPA Hydrologic and Water Quality Data

v2.7.10

CC0

Authors

Laura DeCicco [aut, cre] (<https://orcid.org/0000-0002-3915-9487>), Robert Hirsch [aut] (<https://orcid.org/0000-0002-4534-075X>), David Lorenz [aut], Jordan Read [ctb], Jordan Walker [ctb], Lindsay Carr [ctb], David Watkins [aut] (<https://orcid.org/0000-0002-7544-0700>), David Blodgett [ctb], Mike Johnson [aut] (<https://orcid.org/0000-0002-5288-8350>)

Initial release