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
. IfTRUE
, 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)
#> GET:https://nwis.waterdata.usgs.gov/nwis/gwlevels?site_no=434400121275801&format=rdb&group_key=NONE&date_format=YYYY-MM-DD&rdb_compression=value
sites <- c("434400121275801", "375907091432201")
data2 <- readNWISgwl(sites, "", "")
#> GET:https://nwis.waterdata.usgs.gov/nwis/gwlevels?site_no=434400121275801%2C375907091432201&format=rdb&group_key=NONE&date_format=YYYY-MM-DD&rdb_compression=value
data3 <- readNWISgwl("420125073193001", "", "")
#> GET:https://nwis.waterdata.usgs.gov/nwis/gwlevels?site_no=420125073193001&format=rdb&group_key=NONE&date_format=YYYY-MM-DD&rdb_compression=value
# handling of data where date has no day
data4 <- readNWISgwl("425957088141001", startDate = "1980-01-01")
#> GET:https://nwis.waterdata.usgs.gov/nwis/gwlevels?site_no=425957088141001&format=rdb&begin_date=1980-01-01&group_key=NONE&date_format=YYYY-MM-DD&rdb_compression=value
#> Not all dates were converted to Date object. Returning raw text for date columns.
data5 <- readNWISgwl("263819081585801", parameterCd = "72019")
#> GET:https://nwis.waterdata.usgs.gov/nwis/gwlevels?site_no=263819081585801&format=rdb&group_key=NONE&date_format=YYYY-MM-DD&rdb_compression=value
# }