Imports data from NWIS web service. This function gets the data from here:
https://waterservices.usgs.gov/docs/instantaneous-values/instantaneous-values-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 arguement service="uv".
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 "uv"
returned from whatNWISdata) are available from this service.
Arguments
- siteNumbers
character USGS site number (or multiple sites). This is usually an 8 digit number
- parameterCd
character USGS parameter code. This is usually an 5 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. Simple date arguments are specified in local time. See more information here: https://waterservices.usgs.gov/docs/instantaneous-values/.
- endDate
character ending date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates retrieval for the latest possible record. Simple date arguments are specified in local time. See more information here: https://waterservices.usgs.gov/docs/instantaneous-values/.
- 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 |
| dateTime | POSIXct | The date and time of the value converted to UTC |
| tz_cd | character | The time zone code for dateTime |
| code | character | Any codes that qualify the corresponding value |
| value | numeric | The numeric value for the parameter |
Note that code and value are repeated for the parameters requested. The names are of the form: X_D_P_S, where X is literal, D is an option description of the parameter, P is the parameter code, and S is the statistic code (if applicable).
There are also several useful attributes attached to the data frame:
| Name | Type | Description |
| url | character | The url used to generate the data |
| siteInfo | data.frame | A data frame containing information on the requested sites |
| variableInfo | data.frame | A data frame containing information on the requested parameters |
| statisticInfo | data.frame | A data frame containing information on the requested statistics on the data |
| queryTime | POSIXct | The time the data was returned |
Details
More information on the web service can be found here: https://waterservices.usgs.gov/test-tools, choosing the "Instantaneous Value Service".
Examples
site_id <- "05114000"
parameterCd <- "00060"
startDate <- "2014-10-10"
endDate <- "2014-10-10"
# \donttest{
rawData <- readNWISuv(site_id, parameterCd, startDate, endDate)
#> GET:https://nwis.waterservices.usgs.gov/nwis/iv/?site=05114000&format=waterml%2C1.1&ParameterCd=00060&startDT=2014-10-10&endDT=2014-10-10
rawData_today <- readNWISuv(site_id, parameterCd, Sys.Date(), Sys.Date())
#> GET:https://waterservices.usgs.gov/nwis/iv/?site=05114000&format=waterml%2C1.1&ParameterCd=00060&startDT=2024-12-04&endDT=2024-12-04
timeZoneChange <- readNWISuv(
c("04024430", "04024000"), parameterCd,
"2013-11-03", "2013-11-03"
)
#> GET:https://nwis.waterservices.usgs.gov/nwis/iv/?site=04024430%2C04024000&format=waterml%2C1.1&ParameterCd=00060&startDT=2013-11-03&endDT=2013-11-03
centralTime <- readNWISuv(site_id, parameterCd,
"2014-10-10T12:00", "2014-10-10T23:59",
tz = "America/Chicago"
)
#> GET:https://nwis.waterservices.usgs.gov/nwis/iv/?site=05114000&format=waterml%2C1.1&ParameterCd=00060&startDT=2014-10-10T12%3A00&endDT=2014-10-10T23%3A59
#> Waiting 2s for throttling delay ■■■■■■■■■■■■■■■
#> Waiting 2s for throttling delay ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
# Adding 'Z' to the time indicates to the web service to call the data with UTC time:
GMTdata <- readNWISuv(
site_id, parameterCd,
"2014-10-10T00:00Z", "2014-10-10T23:59Z"
)
#> GET:https://nwis.waterservices.usgs.gov/nwis/iv/?site=05114000&format=waterml%2C1.1&ParameterCd=00060&startDT=2014-10-10T00%3A00Z&endDT=2014-10-10T23%3A59Z
#> Waiting 2s for throttling delay ■■■■■■■■■■■■■■■
#> Waiting 2s for throttling delay ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
# }