Groundwater level measurements retrieval from USGS (NWIS)

Imports groundwater level data from NWIS web service. This function gets the data from here: https://waterservices.usgs.gov/docs/groundwater-levels/groundwater-levels-details/ Inputs to this function are just USGS site ids, USGS parameter codes, and start and end date. For a more complex query, use readNWISdata, including an argument service="gwlevels". Not all parameter codes are available for all data. Use the function whatNWISdata to discover what data is available for a USGS site. The column data_type_cd with the values "gw" returned from whatNWISdata) are available from this service.

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

Details

More information on the web service can be found here: https://waterservices.usgs.gov/test-tools, choosing the "Groundwater Levels Value Service".

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/docs/groundwater-levels/ for more information.

Examples

site_id <- "434400121275801"
# \donttest{
data <- readNWISgwl(site_id)
sites <- c("434400121275801", "375907091432201")
data2 <- readNWISgwl(sites, "", "")
data3 <- readNWISgwl("420125073193001", "", "")
# handling of data where date has no day
data4 <- readNWISgwl("425957088141001", startDate = "1980-01-01")
#> Not all dates were converted to Date object. Returning raw text for date columns.

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