Type:	Package
Title:	Retrieval Functions for USGS and EPA Hydrology and Water Quality Data
Version:	2.7.20
Description:	Collection of functions to help retrieve U.S. Geological Survey and U.S. Environmental Protection Agency water quality and hydrology data from web services.
License:	CC0
Copyright:	This software is in the public domain because it contains materials that originally came from the United States Geological Survey, an agency of the United States Department of Interior.
Depends:	R (≥ 4.1.0)
Imports:	curl (≥ 6.0.0), lubridate (≥ 1.5.0), stats, utils, xml2, readr (≥ 1.4.0), jsonlite, httr2, whisker, sf
Suggests:	covr, dplyr, knitr, rmarkdown, testthat
Encoding:	UTF-8
BuildVignettes:	true
VignetteBuilder:	knitr
BugReports:	https://github.com/DOI-USGS/dataRetrieval/issues
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-07-14 20:59:23 UTC; ldecicco
Author:	Laura DeCicco [aut, cre], Robert Hirsch [aut], David Lorenz [aut], Jordan Read [ctb], Jordan Walker [ctb], Lindsay Platt [ctb], David Watkins [aut], David Blodgett [aut], Mike Johnson [aut], Aliesha Krall [ctb], Lee Stanish [ctb], Joeseph Zemmels [ctb], Elise Hinman [ctb], Michael Mahoney [ctb]
Maintainer:	Laura DeCicco <ldecicco@usgs.gov>
Repository:	CRAN
Date/Publication:	2025-07-15 05:10:05 UTC

Retrieval functions for USGS and EPA data

Description

Details

Retrieval functions for USGS and EPA hydrologic and water quality data.

Please see https://doi-usgs.github.io/dataRetrieval/ for more information.

Author(s)

Laura De Cicco ldecicco@usgs.gov

See Also

Useful links:

• Report bugs at https://github.com/DOI-USGS/dataRetrieval/issues

add a water year column

Description

Add a column to the dataRetrieval data frame with the water year. WQP queries will return a water year column for the start and end dates of the data.

Usage

addWaterYear(rawData)

Arguments

Value

data.frame with an additional integer column with "WY" appended to the date column name. For WQP, there will be 2 columns: ActivityStartDateWY and ActivityEndDateWY.

Examples

nwisData <- readNWISdv("04085427", "00060", "2022-01-01", "2022-06-30")
nwisData <- addWaterYear(nwisData)

wqpData <- readWQPqw("USGS-01594440", "01075", "", "")
wqpData <- addWaterYear(wqpData)

Extract WY from a date

Description

Determine the correct water year based on a calendar date.

Usage

calcWaterYear(dateVec)

Arguments

Details

This function calculates a water year based on the USGS definition that a water year starts on October 1 of the year before, and ends on September 30. For example, water year 2015 started on 2014-10-01 and ended on 2015-09-30.

Value

numeric vector indicating the water year

Examples

x <- seq(as.Date("2010-01-01"), as.Date("2010-12-31"), by = "month")
calcWaterYear(x)

y <- c("2010-01-01", "1994-02", "1980", "2009-11-01", NA)
calcWaterYear(y)

Date Check for Water Quality Portal

Description

Checks date format for inputs to the Water Quality Portal. Used in readWQPqw and readWQPdata.

Usage

checkWQPdates(values)

Arguments

Value

values named list with corrected arguments to send to the Water Quality Portal

Examples

values <- list(
  startDateLo = "01-01-2002",
  characteristicName = "Phosphorous",
  endDate = as.Date("2014-01-01")
)
values <- checkWQPdates(values)

Check OGC requests

Description

Check OGC requests

Usage

check_OGC_requests(endpoint = "daily", type = "queryables")

Arguments

Value

list

Examples

dv_queryables <- check_OGC_requests(endpoint = "daily",
                                type = "queryables")
dv_schema <- check_OGC_requests(endpoint = "daily",
                            type = "schema")
ts_meta_queryables <- check_OGC_requests(endpoint = "time-series-metadata",
                                type = "queryables")
ts_meta_schema <- check_OGC_requests(endpoint = "time-series-metadata",
                                type = "schema")

Check values from codeservice

Description

Call a service to check on values from: https://api.waterdata.usgs.gov/samples-data/codeservice/docs.

Usage

check_waterdata_sample_params(service = "characteristicgroup", ...)

Arguments

Value

List, structure depends on service.

Examples

groups <- check_waterdata_sample_params("characteristicgroup")
states <- check_waterdata_sample_params("states")
countries <- check_waterdata_sample_params("countries")
counties <- check_waterdata_sample_params("counties")
sitetypes <- check_waterdata_sample_params("sitetype")
samplemedia <- check_waterdata_sample_params("samplemedia")
characteristics <- check_waterdata_sample_params("characteristics",
                               group = "Biological")
observedProperties <- check_waterdata_sample_params("observedproperty",
                                  text = "phosphorus")
ref_list <- check_waterdata_sample_params("reference-list")

Construct NWIS url for data retrieval

Description

Using USGS water web services to construct urls.

Usage

constructNWISURL(
  siteNumbers,
  parameterCd = "00060",
  startDate = "",
  endDate = "",
  service,
  statCd = "00003",
  format = "xml",
  expanded = TRUE,
  ratingType = "base",
  statReportType = "daily",
  statType = "mean"
)

Arguments

Value

url string

Examples

site_id <- "01594440"
startDate <- "1985-01-01"
endDate <- ""
pCode <- c("00060", "00010")
url_daily <- constructNWISURL(site_id, pCode,
  startDate, endDate, "dv",
  statCd = c("00003", "00001")
)
url_unit <- constructNWISURL(site_id, pCode, "2012-06-28", "2012-06-30", "iv")

url_daily_tsv <- constructNWISURL(site_id, pCode, startDate, endDate, "dv",
  statCd = c("00003", "00001"), format = "tsv"
)
url_rating <- constructNWISURL(site_id, service = "rating", ratingType = "base")
url_peak <- constructNWISURL(site_id, service = "peak")
url_meas <- constructNWISURL(site_id, service = "meas")
url_gwl <- constructNWISURL(site_id, service = "gwlevels",
                            startDate = "2024-05-01", endDate = "2024-05-30")

Construct URL for NWIS water use data service

Description

Reconstructs URLs to retrieve data from here: https://waterdata.usgs.gov/nwis/wu

Usage

constructUseURL(years, stateCd, countyCd, categories)

Arguments

Value

url string

Examples

url <- constructUseURL(
  years = c(1990, 1995),
  stateCd = "Ohio",
  countyCd = c(1, 3),
  categories = "ALL"
)

Construct WQP url for data retrieval

Description

Construct WQP url for data retrieval. This function gets the data from here: https://www.waterqualitydata.us

Usage

constructWQPURL(siteNumbers, parameterCd, startDate, endDate, legacy = TRUE)

Arguments

Value

url string

Examples

site_ids <- c("USGS-02292010", "USGS-02276877")
startDate <- "2020-01-01"
endDate <- ""
pCode <- c("80154", "00613")
url_wqp <- constructWQPURL(
  site_ids,
  pCode,
  startDate, endDate
)
url_wqp
charNames <- c(
  "Temperature",
  "Temperature, sample",
  "Temperature, water",
  "Temperature, water, deg F"
)
obs_url_orig <- constructWQPURL(
  siteNumbers = c(
    "IIDFG-41WSSPAHS",
    "USGS-02352560"
  ),
  parameterCd = charNames,
  startDate, ""
)
obs_url_orig

Create API url

Description

Main documentation: https://api.waterdata.usgs.gov/ogcapi/v0/, Swagger docs: https://api.waterdata.usgs.gov/ogcapi/v0/openapi?f=html.

Usage

construct_api_requests(
  service,
  properties = NA_character_,
  bbox = NA,
  limit = NA,
  max_results = NA,
  skipGeometry = FALSE,
  ...
)

Arguments

Examples

site <- "USGS-02238500"
pcode <- "00060"
req_dv <- construct_api_requests("daily",
                                 monitoring_location_id = site,
                                 parameter_code = "00060")

req_dv <- construct_api_requests("daily",
                                 monitoring_location_id = site,
                                 parameter_code = c("00060", "00065"))

sites <- c("USGS-01491000", "USGS-01645000")
start_date <- "2018-01-01"
end_date <- "2022-01-01"
req_dv <- construct_api_requests("daily",
                                monitoring_location_id = sites,
                                parameter_code = c("00060", "00065"),
                                datetime = c(start_date, end_date))

Construct request for USGS Samples Data

Description

This function creates the call for discrete water quality samples data service described at https://waterdata.usgs.gov/download-samples/. Note: all possible arguments are included, but it is strongly recommended to only use the NECESSARY arguments. Leave unnecessary arguments as the default NA.

Usage

construct_waterdata_sample_request(
  monitoringLocationIdentifier = NA,
  siteTypeCode = NA,
  boundingBox = NA,
  hydrologicUnit = NA,
  activityMediaName = NA,
  characteristicGroup = NA,
  characteristic = NA,
  characteristicUserSupplied = NA,
  activityStartDateLower = NA,
  activityStartDateUpper = NA,
  countryFips = NA,
  stateFips = NA,
  countyFips = NA,
  projectIdentifier = NA,
  recordIdentifierUserSupplied = NA,
  siteTypeName = NA,
  usgsPCode = NA,
  pointLocationLatitude = NA,
  pointLocationLongitude = NA,
  pointLocationWithinMiles = NA,
  dataType = "results",
  dataProfile = NA
)

Arguments

Details

See also: https://api.waterdata.usgs.gov/samples-data/docs.

Value

data frame returned from web service call.

Examples

req <- construct_waterdata_sample_request(
               monitoringLocationIdentifier = "USGS-04074950",
               characteristicUserSupplied = "pH, water, unfiltered, field")
rawData <- importWQP(req)

convert variables in dots to usable format

Description

convert variables in dots to usable format

Usage

convertLists(...)

US County Code Lookup Table

Description

Classic lookup table for counties. Has been replaced in functions with check_waterdata_sample_params("counties").

Value

countyCd data frame.

Examples

head(countyCd)

US county code look up

Description

Function to simplify finding county and county code definitions. Used in readNWISdata and readNWISuse. Currently only has US counties.

Usage

countyCdLookup(state, county, outputType = "fips")

Arguments

Examples

fips <- countyCdLookup(state = "WI", county = "Dane")
id <- countyCdLookup(state = "WI", county = "Dane", outputType = "id")
name <- countyCdLookup(state = "OH", county = 13, output = "fullName")
entry <- countyCdLookup(state = "Pennsylvania", county = "ALLEGHENY COUNTY", output = "fullEntry")
fromIDs <- countyCdLookup(state = 13, county = 5, output = "fullName")

Create NWIS data citation

Description

Uses attributes from the NWIS functions to create data citations.

Usage

create_NWIS_bib(x)

Arguments

Details

See ?bibentry for more information.

Value

bibentry object to use for citing the data.

Examples

nwisData <- readNWISdv("04085427", "00060", "2012-01-01", "2012-06-30")
nwis_citation <- create_NWIS_bib(nwisData)
nwis_citation

print(nwis_citation, style = "Bibtex")
print(nwis_citation, style = "citation")

Create WQP data citation

Description

Uses attributes from the WQP functions to create data citations.

Usage

create_WQP_bib(x)

Arguments

Details

See ?bibentry for more information.

Value

bibentry object to use for citing the data.

Examples

WQPData <- readWQPqw("USGS-05288705",
                     parameterCd = "00300")
wqp_citation <- create_WQP_bib(WQPData)
wqp_citation

print(wqp_citation, style = "Bibtex")
print(wqp_citation, style = "citation")

Create user agent

Description

Create user agent

Usage

default_ua()

R Client for the Network Linked Data Index

Description

Provides a formal client to the USGS Network Linked Data Index.

Usage

findNLDI(
  comid = NULL,
  nwis = NULL,
  wqp = NULL,
  huc12 = NULL,
  location = NULL,
  origin = NULL,
  nav = NULL,
  find = c("flowlines"),
  distance_km = 100,
  no_sf = FALSE,
  warn = TRUE
)

Arguments

Details

The function is useful for topology and location based feature discovery. A user must specify an origin feature, optional navigation direction(s) along the network, as well as features to identify along the navigated paths. Valid starting options can be given by one of the following arguments: comid, nwis, huc12, wqp, location, and start.

Value

a list of data.frames if sf is not installed, a list of sf objects if it is

Examples

# Find Features / Define origin features

## Find feature by COMID
findNLDI(comid = 101)

## Find feature by NWIS ID
findNLDI(nwis = "11120000")


## Find feature by LOCATION
findNLDI(location = c(-115, 40))

## GENERAL ORIGIN: COMID
findNLDI(origin = list("comid" = 101))

# Navigation (flowlines will be returned if find is unspecified)
# UPPER MAINSTEM of USGS-11120000
findNLDI(nwis = "11120000", nav = "UM")

# MULTI-REQUEST
# UPPER MAINSTEM and TRIBUTARY of USGS-11120000
findNLDI(nwis = "11120000", nav = c("UT", "UM"))

# Discover Features(flowlines will not be returned unless included in find)

## Find feature(s) on the upper tributary of USGS-11120000
findNLDI(nwis = "11120000", nav = "UT", find = c("nwis"))

## Find upstream basin boundary and  of USGS-11120000
findNLDI(nwis = "11120000", find = "basin")

# Control Distance
## Limit search to 50 km
findNLDI(comid = 101, nav = "DM", find = c("nwis", "flowlines"), distance_km = 50)

getting header information from a WQP query

Description

getting header information from a WQP query

Usage

getQuerySummary(url)

Arguments

Function to return data from web services

Description

This function accepts a url parameter, and returns the raw data.

Usage

getWebServiceData(obs_url, ...)

Arguments

Details

To add a custom user agent, create an environmental variable: CUSTOM_DR_UA

Value

Returns xml, json, or text depending on the requested data.

Examples

siteNumber <- "02177000"
startDate <- "2012-09-01"
endDate <- "2012-10-01"
offering <- "00003"
property <- "00060"
obs_url <- constructNWISURL(siteNumber, property, startDate, endDate, "dv")

rawData <- getWebServiceData(obs_url)

Get current NLDI offerings

Description

Used to query the current resources available through the NLDI

Usage

get_nldi_sources(url = pkg.env$nldi_base)

Arguments

Value

data.frame

Examples

get_nldi_sources()

has_internet_2

Description

Function to check for internet even if the user is behind a proxy

Usage

has_internet_2(obs_url)

Arguments

Details

If this is giving you problems, override the false negative: Sys.setenv("OVERRIDE_INTERNET_TEST" = TRUE)

Function to return data from the National Ground Water Monitoring Network waterML2 format

Description

This function accepts a url parameter for a WaterML2 getObservation. This function is still under development, but the general functionality is correct.

Usage

importNGWMN(input, asDateTime = FALSE, tz = "UTC")

Arguments

Value

mergedDF a data frame source, time, value, uom, uomTitle, comment, gmlID

Examples

params <- list(request = "GetObservation",
               service = "SOS",
               version = "2.0.0",
               observedProperty = "urn:ogc:def:property:OGC:GroundWaterLevel",
               responseFormat = "text/xml",
               featureOfInterest = "VW_GWDP_GEOSERVER.USGS.403836085374401")

obs_url <- httr2::request("https://cida.usgs.gov") |>
 httr2::req_url_path_append("ngwmn_cache") |> 
 httr2::req_url_path_append("sos") |>
 httr2::req_url_query(!!!params)

#data_returned <- importNGWMN(obs_url)

Function to return data from the NWIS RDB 1.0 format

Description

This function accepts a url parameter that already contains the desired NWIS site, parameter code, statistic, startdate and enddate. It is not recommended to use the RDB format for importing multi-site data.

Usage

importRDB1(obs_url, asDateTime = TRUE, convertType = TRUE, tz = "UTC")

Arguments

Value

A data frame with the following columns:

Note that code and value are repeated for the parameters requested. The names are of the form XD_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). If a date/time (dt) column contained incomplete date and times, a new column of dates and time was inserted. This could happen when older data was reported as dates, and newer data was reported as a date/time.

There are also several useful attributes attached to the data frame:

Examples

site_id <- "02177000"
startDate <- "2012-09-01"
endDate <- "2012-10-01"
offering <- "00003"
property <- "00060"

obs_url <- constructNWISURL(site_id, property,
  startDate, endDate, "dv",
  format = "tsv"
)

data <- importRDB1(obs_url)


urlMultiPcodes <- constructNWISURL("04085427", c("00060", "00010"),
  startDate, endDate, "dv",
  statCd = c("00003", "00001"), "tsv"
)

multiData <- importRDB1(urlMultiPcodes)

unitDataURL <- constructNWISURL(site_id, property,
  "2020-10-30", "2020-11-01", "uv",
  format = "tsv"
) # includes timezone switch

unitData <- importRDB1(unitDataURL, asDateTime = TRUE)

iceSite <- "04024000"
start <- "2015-11-09"
end <- "2015-11-24"
urlIce <- constructNWISURL(iceSite, "00060", start, end, "uv", format = "tsv")

ice <- importRDB1(urlIce, asDateTime = TRUE)
iceNoConvert <- importRDB1(urlIce, convertType = FALSE)

# User file:
filePath <- system.file("extdata", package = "dataRetrieval")
fileName <- "RDB1Example.txt"
fullPath <- file.path(filePath, fileName)
importUserRDB <- importRDB1(fullPath)

Basic Water Quality Portal Data parser

Description

Imports data from the Water Quality Portal based on a specified url.

Usage

importWQP(obs_url, tz = "UTC", csv = TRUE, convertType = TRUE)

Arguments

Value

retval dataframe raw data returned from the Water Quality Portal. Additionally, a POSIXct dateTime column is supplied for start and end times, and converted to UTC. See https://www.waterqualitydata.us/portal_userguide/ for more information.

See Also

readWQPdata(), readWQPqw(), whatWQPsites()

Examples

# These examples require an internet connection to run

## Examples take longer than 5 seconds:

rawSampleURL <- constructWQPURL("USGS-01594440", "01075", "", "")

rawSample <- importWQP(rawSampleURL)


STORETex <- constructWQPURL("WIDNR_WQX-10032762", "Specific conductance", "", "")

STORETdata <- importWQP(STORETex)

STORETdata_char <- importWQP(STORETex, convertType = FALSE)

Function to return data from the NWISWeb WaterML1.1 service

Description

This function accepts a url parameter that already contains the desired NWIS site, parameter code, statistic, startdate and enddate.

Usage

importWaterML1(obs_url, asDateTime = FALSE, tz = "UTC")

Arguments

Value

A data frame with the following columns:

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:

See Also

renameNWISColumns()

Examples

site_id <- "02177000"
startDate <- "2012-09-01"
endDate <- "2012-10-01"
offering <- "00003"
property <- "00060"
obs_url <- constructNWISURL(site_id, property, startDate, endDate, "dv")

data <- importWaterML1(obs_url, asDateTime = TRUE)


unitDataURL <- constructNWISURL(
  site_id, property,
  "2013-11-03", "2013-11-03", "uv"
)
unitData <- importWaterML1(unitDataURL, TRUE)

# Two sites, two pcodes, one site has two data descriptors:
siteNumber <- c("01480015", "04085427")
obs_url <- constructNWISURL(
  siteNumber, c("00060", "00010"),
  startDate, endDate, "dv"
)
data <- importWaterML1(obs_url)
data$dateTime <- as.Date(data$dateTime)
data <- renameNWISColumns(data)
names(attributes(data))
attr(data, "url")
attr(data, "disclaimer")

inactiveSite <- "05212700"
inactiveSite <- constructNWISURL(inactiveSite, "00060", 
                                 "2014-01-01", "2014-01-10", "dv")
inactiveSite <- importWaterML1(inactiveSite)

inactiveAndAcitive <- c("07334200", "05212700")
inactiveAndAcitive <- constructNWISURL(inactiveAndAcitive, 
                         "00060", "2014-01-01", "2014-01-10", "dv")
inactiveAndAcitive <- importWaterML1(inactiveAndAcitive)

# Timezone change with specified local timezone:
tzURL <- constructNWISURL("04027000", c("00300", "63680"), 
                          "2011-11-05", "2011-11-07", "uv")
tzIssue <- importWaterML1(tzURL,
  asDateTime = TRUE, tz = "America/Chicago"
)


filePath <- system.file("extdata", package = "dataRetrieval")
fileName <- "WaterML1Example.xml"
fullPath <- file.path(filePath, fileName)
importFile <- importWaterML1(fullPath, TRUE)

Parse the WaterML2 timeseries portion of a waterML2 file

Description

Returns data frame columns of all information with each time series measurement; Anything defined as a default, is returned as an attribute of that data frame.

Usage

importWaterML2(input, asDateTime = FALSE, tz = "UTC")

Arguments

Examples

baseURL <- httr2::request("https://waterservices.usgs.gov/nwis/dv")
baseURL <- httr2::req_url_query(baseURL,
                                format = "waterml,2.0",
                                sites = "01646500",
                                startDT = "2014-09-01",
                                endDT = "2014-09-08",
                                statCd = "00003",
                                parameterCd = "00060" )

timeseries <- importWaterML2(baseURL, asDateTime = TRUE, tz = "UTC")

Is this a dataRetrieval user

Description

Reveals if this is a user or not

Usage

is_dataRetrieval_user()

Examples

is_dataRetrieval_user()

Data to convert USGS parameter code to characteristic names

Description

Data pulled from Water Quality Portal on December 20, 2021. The data was pulled from https://www.waterqualitydata.us/Codes/public_srsnames/?mimeType=csv.

Value

pCodeToName data frame with information about USGS parameters and how they relate to characteristic names (useful for WQP requests).

Examples

head(pCodeToName[, 1:2])

List of USGS parameter codes

Description

Complete list of USGS parameter codes as of Oct. 24, 2024.

Value

parameterData data frame with information about USGS parameters.

Examples

head(parameterCdFile[, 1:2])

Convert WQP columns to correct types

Description

Takes the character results and converts to numeric and dates.

Usage

parse_WQP(retval, tz = "UTC")

Arguments

Value

data frame retval with converted columns

Examples

# These examples require an internet connection to run
rawSampleURL <- constructWQPURL("USGS-01594440", "01075", "", "")

## Examples take longer than 5 seconds:



rawSample <- importWQP(rawSampleURL, convertType = FALSE)
convertedSample <- parse_WQP(rawSample)

 

Parameter code to characteristic name

Description

This function is useful to fine what characteristic name, result sample fraction, unit code, and other parameters are mapped with USGS parameter codes. This information is useful for converting workflows from a more traditional NWIS water quality retrieval to a Water Quality Portal retrieval.

Usage

pcode_to_name(parameterCd = "all")

Arguments

Value

a data frame with columns "parm_cd", "description", "characteristicname", "measureunitcode", "resultsamplefraction", "resulttemperaturebasis", "resultstatisticalbasis", "resulttimebasis", "resultweightbasis", "resultparticlesizebasis", "last_rev_dt"

Examples

pcodes <- c("00070", "00075", "00430", "52642")


all <- pcode_to_name()
some <- pcode_to_name(pcodes)

Import data from the National Groundwater Monitoring Network.

Description

Only water level data and site locations and names are currently available through the web service.

Usage

readNGWMNdata(service, ..., asDateTime = TRUE, tz = "UTC")

Arguments

Examples

# one site
site <- "USGS.430427089284901"
#oneSite <- readNGWMNdata(siteNumbers = site, service = "observation")

# multiple sites
sites <- c("USGS.272838082142201", "USGS.404159100494601", "USGS.401216080362703")
# Very slow:
# multiSiteData <- readNGWMNdata(siteNumbers = sites, service = "observation")
# attributes(multiSiteData)

# non-USGS site
# accepts colon or period between agency and ID
site <- "MBMG:702934"
# data <- readNGWMNdata(siteNumbers = site, service = "featureOfInterest")

# bounding box
# bboxSites <- readNGWMNdata(service = "featureOfInterest", bbox = c(30, -102, 31, 99))
# retrieve  sites.  Set asDateTime to false since one site has an invalid date
# Very slow:
# bboxData <- readNGWMNdata(service = "observation", siteNumbers = bboxSites$site[1:3],
#                           asDateTime = FALSE)

Retrieve groundwater levels from the National Ground Water Monitoring Network.

Description

Retrieve groundwater levels from the National Ground Water Monitoring Network.

Usage

readNGWMNlevels(siteNumbers, asDateTime = TRUE, tz = "UTC")

Arguments

Examples

# one site
site <- "USGS.430427089284901"
# oneSite <- readNGWMNlevels(siteNumbers = site)

# multiple sites
sites <- c("USGS:272838082142201", "USGS:404159100494601", "USGS:401216080362703")
# multiSiteData <- readNGWMNlevels(sites)

# non-USGS site
site <- "MBMG.103306"
# data <- readNGWMNlevels(siteNumbers = site, asDateTime = FALSE)

# site with no data returns empty data frame
noDataSite <- "UTGS.401544112060301"
# noDataSite <- readNGWMNlevels(siteNumbers = noDataSite)

Retrieve site data from the National Ground Water Monitoring Network.

Description

Retrieve site data from the National Ground Water Monitoring Network.

Usage

readNGWMNsites(siteNumbers)

Arguments

Value

A data frame the following columns: #'

Examples

# one site
site <- "USGS.430427089284901"
#oneSite <- readNGWMNsites(siteNumbers = site)

# non-USGS site
site <- "MBMG.103306"
#siteInfo <- readNGWMNsites(siteNumbers = site)

General Data Import from NWIS

Description

Returns data from the NWIS web service. Arguments to the function should be based on https://waterservices.usgs.gov service calls. See examples below for ideas of constructing queries.

Usage

readNWISdata(..., asDateTime = TRUE, convertType = TRUE, tz = "UTC")

Arguments

Details

This function requires users to create their own arguments based on the NWIS web services. It is a more complicated function to use compared to other NWIS functions such as readNWISdv(), readNWISuv(), readNWISgwl(), etc. However, this function adds a lot of flexibility to the possible queries. This function will also behave exactly as NWIS when it comes to date queries. NWIS by default will only return the latest value for the daily and instantaneous services. So if you do not provide a starting date, you will only get back the latest value. If you want the full period of record, you can use "startDate = '1900-01-01'". Other options for dates are periods, such as "period = 'P7D'" which translates to a period of 7 days. For period, use only a positive ISO-8601 duration format, which should not be expressed in periods of less than a day, or in increments of months M or years Y. period returns data for a site generally from now to a time in the past. Note that when period is used all data up to the most recent value are returned.

Value

A data frame with the following columns:

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:

See Also

read_waterdata()

Examples

# Examples not run for time considerations

instFlow <- readNWISdata(
  sites = "05114000", service = "iv",
  parameterCd = "00060",
  startDate = "2014-05-01T00:00Z", endDate = "2014-05-01T12:00Z"
)

instFlowCDT <- readNWISdata(
  sites = "05114000", service = "iv",
  parameterCd = "00060",
  startDate = "2014-05-01T00:00", endDate = "2014-05-01T12:00",
  tz = "America/Chicago"
)

multiSite <- readNWISdata(
  sites = c("04025500", "040263491"),
  service = "iv", parameterCd = "00060"
)


GWL <- readNWISdata(site_no = c("392725077582401", 
                                "375907091432201"),
                    parameterCd = "62610",
                    service = "gwlevels")
                    
levels <- readNWISdata(stateCd = "WI", 
                       service = "gwlevels",
                       startDate = "2024-05-01",
                       endDate = "2024-05-30") 
                    
meas <- readNWISdata(
  state_cd = "WI", service = "measurements",
  format = "rdb_expanded"
)

waterYearStat <- readNWISdata(
  site = c("01646500"),
  service = "stat",
  statReportType = "annual",
  statYearType = "water",
  missingData = "on"
)
monthlyStat <- readNWISdata(
  site = c("01646500"),
  service = "stat",
  statReportType = "monthly"
)

dailyStat <- readNWISdata(
  site = c("01646500"),
  service = "stat",
  statReportType = "daily",
  statType = c("p25", "p50", "p75", "min", "max"),
  parameterCd = "00060"
)

arg.list <- list(
  site = "03111548",
  statReportType = "daily",
  statType = c("p25", "p50", "p75", "min", "max"),
  parameterCd = "00060"
)
allDailyStats_2 <- readNWISdata(arg.list, service = "stat")


site_id <- "01594440"
rating_curve <- readNWISdata(service = "rating", site_no = site_id, file_type = "base")
all_sites_base <- readNWISdata(service = "rating", file_type = "base")
all_sites_core <- readNWISdata(service = "rating", file_type = "corr")
all_sites_exsa <- readNWISdata(service = "rating", file_type = "exsa")
all_sites_24hrs <- readNWISdata(service = "rating", file_type = "exsa", period = 24)

peak_data <- readNWISdata(
  service = "peak",
  site_no = c("01594440", "040851325"),
  range_selection = "data_range"
)

peak_data <- readNWISdata(
  service = "peak",
  state_cd = "PA"
)

peak_data <- readNWISdata(
  service = "peak",
  huc2_cd = "20"
)

Format and organize NWIS arguments that are passed in as ....

Description

Format and organize NWIS arguments that are passed in as ....

Usage

readNWISdots(...)

Daily Value USGS NWIS Data Retrieval

Description

Imports data from NWIS daily web service. This function gets the data from here: https://waterservices.usgs.gov/docs/dv-service/daily-values-service-details/ Inputs to this function are just USGS site ids, USGS parameter codes, USGS statistic codes, and start and end date. For a more complex query, use readNWISdata(), with an argument service = "dv". Data coming the daily web services are aggregates of the instantaneous (sensor) web services. Not all statistical 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 "dv" returned from whatNWISdata()) are available from this service.

Usage

readNWISdv(
  siteNumbers,
  parameterCd,
  startDate = "",
  endDate = "",
  statCd = "00003"
)

Arguments

Details

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

Value

A data frame with the following columns:

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:

See Also

read_waterdata_daily()

Examples

# see ?read_waterdata_daily

#site_id <- "04085427"
#startDate <- "2012-01-01"
#endDate <- "2012-06-30"
#pCode <- "00060"
#
#rawDailyQ <- readNWISdv(site_id, pCode, startDate, endDate)

Groundwater level measurements retrieval from USGS (NWIS)

Description

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

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.

Value

A data frame with the following columns:

There are also several useful attributes attached to the data frame:

See Also

constructNWISURL(), importRDB1()

Examples

site_id <- "434400121275801"

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")

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

Surface-water measurement data retrieval from USGS (NWIS)

Description

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

Value

A data frame with at least the following columns:

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:

See Also

constructNWISURL(), importRDB1()

Examples

site_ids <- c("01594440", "040851325")

data <- readNWISmeas(site_ids)
Meas05316840 <- readNWISmeas("05316840")
Meas05316840.ex <- readNWISmeas("05316840", expanded = TRUE)
Meas07227500.ex <- readNWISmeas("07227500", expanded = TRUE)
Meas07227500.exRaw <- readNWISmeas("07227500", expanded = TRUE, convertType = FALSE)

USGS Parameter Data Retrieval

Description

Imports data from NWIS about measured parameter based on user-supplied parameter code or codes. This function gets the data from here: https://nwis.waterdata.usgs.gov/nwis/pmcodes

Usage

readNWISpCode(parameterCd)

Arguments

Value

parameterData data frame with the following information:

See Also

importRDB1()

Peak flow data from USGS (NWIS)

Description

Reads peak flow from NWISweb. Data is retrieved from https://waterdata.usgs.gov/nwis. In some cases, the specific date of the peak data is not know. This function will default to converting complete dates to a "Date" object, and converting incomplete dates to "NA". If those incomplete dates are needed, set the asDateTime argument to FALSE. No dates will be converted to R Date objects.

Usage

readNWISpeak(
  siteNumbers,
  startDate = "",
  endDate = "",
  asDateTime = TRUE,
  convertType = TRUE
)

Arguments

Value

A data frame with the following columns:

There are also several useful attributes attached to the data frame:

See Also

constructNWISURL(), importRDB1()

Examples

site_ids <- c("01594440", "040851325")

data <- readNWISpeak(site_ids)
data2 <- readNWISpeak(site_ids, asDateTime = FALSE)
stations <- c("06011000")
peakdata <- readNWISpeak(stations, convertType = FALSE)

Rating table for an active USGS streamgage retrieval

Description

Reads current rating table for an active USGS streamgage from NWISweb. Data is retrieved from https://waterdata.usgs.gov/nwis.

Usage

readNWISrating(siteNumber, type = "base", convertType = TRUE)

Arguments

Value

A data frame. If type is "base, " then the columns are INDEP, typically the gage height, in feet; DEP, typically the streamflow, in cubic feet per second; and STOR, where "*" indicates that the pair are a fixed point of the rating curve. If type is "exsa, " then an additional column, SHIFT, is included that indicates the current shift in the rating for that value of INDEP. If type is "corr, " then the columns are INDEP, typically the gage height, in feet; CORR, the correction for that value; and CORRINDEP, the corrected value for CORR.
If type is "base, " then the data frame has an attribute called "RATING" that describes the rating curve is included.

There are also several useful attributes attached to the data frame:

Note

Not all active USGS streamgages have traditional rating curves that relate flow to stage.

See Also

constructNWISURL(), importRDB1()

Examples

site_id <- "01594440"

data <- readNWISrating(site_id, "base")
attr(data, "RATING")

USGS Site File Data Retrieval

Description

Imports data from USGS site file site. This function gets data from here: https://waterservices.usgs.gov/

Usage

readNWISsite(siteNumbers)

Arguments

Value

A data frame with at least the following columns:

There are also several useful attributes attached to the data frame:

See Also

read_waterdata_monitoring_location()

Examples

# see ?read_waterdata_monitoring_location
# siteINFOMulti <- readNWISsite(c("05114000", "09423350"))

Site statistics retrieval from USGS (NWIS)

Description

Retrieves site statistics from the USGS Statistics Web Service beta. See https://waterservices.usgs.gov/docs/statistics/ for more information.

Usage

readNWISstat(
  siteNumbers,
  parameterCd,
  startDate = "",
  endDate = "",
  convertType = TRUE,
  statReportType = "daily",
  statType = "mean"
)

Arguments

Value

A data frame with the following columns:

See Also

constructNWISURL(), importRDB1()

Examples

x1 <- readNWISstat(
  siteNumbers = c("02319394"),
  parameterCd = c("00060"),
  statReportType = "annual"
)

# all the annual mean discharge data for two sites
x2 <- readNWISstat(
  siteNumbers = c("02319394", "02171500"),
  parameterCd = c("00010", "00060"),
  statReportType = "annual"
)

# Request p25, p75, and mean values for temperature and discharge for the 2000s
# Note that p25 and p75 were not available for temperature, and return NAs
x <- readNWISstat(
  siteNumbers = c("02171500"),
  parameterCd = c("00010", "00060"),
  statReportType = "daily",
  statType = c("mean", "median"),
  startDate = "2000", endDate = "2010"
)

Water use data retrieval from USGS (NWIS)

Description

Retrieves water use data from USGS Water Use Data for the Nation. See https://waterdata.usgs.gov/nwis/wu for more information. All available use categories for the supplied arguments are retrieved.

Usage

readNWISuse(
  stateCd,
  countyCd,
  years = "ALL",
  categories = "ALL",
  convertType = TRUE,
  transform = FALSE
)

Arguments

Value

A data frame with at least the year of record, and all available statistics for the given geographic parameters. County and state fields will be included as appropriate.

Examples

# All data for a county
allegheny <- readNWISuse(stateCd = "Pennsylvania", countyCd = "Allegheny")

# Data for an entire state for certain years
ohio <- readNWISuse(years = c(2000, 2005, 2010), stateCd = "OH", countyCd = NULL)

# Data for an entire state, county by county
pr <- readNWISuse(years = c(2000, 2005, 2010), stateCd = "PR", countyCd = "ALL")

# All national-scale data, transforming data frame to named columns from named rows
national <- readNWISuse(stateCd = NULL, countyCd = NULL, transform = TRUE)

# Washington, DC data
dc <- readNWISuse(stateCd = "DC", countyCd = NULL)

# data for multiple counties, with different input formatting
paData <- readNWISuse(stateCd = "42", countyCd = c("Allegheny County", "BUTLER", 1, "031"))

# retrieving two specific categories for an entire state
ks <- readNWISuse(stateCd = "KS", countyCd = NULL, categories = c("IT", "LI"))

Instantaneous value data retrieval from USGS (NWIS)

Description

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.

Usage

readNWISuv(siteNumbers, parameterCd, startDate = "", endDate = "", tz = "UTC")

Arguments

Details

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

Value

A data frame with the following columns:

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:

See Also

renameNWISColumns(), importWaterML1()

Examples

site_id <- "05114000"
parameterCd <- "00060"
startDate <- "2014-10-10"
endDate <- "2014-10-10"


rawData <- readNWISuv(site_id, parameterCd, startDate, endDate)

rawData_today <- readNWISuv(site_id, parameterCd, Sys.Date(), Sys.Date())

timeZoneChange <- readNWISuv(
  c("04024430", "04024000"), parameterCd,
  "2013-11-03", "2013-11-03"
)

centralTime <- readNWISuv(site_id, parameterCd,
  "2014-10-10T12:00", "2014-10-10T23:59",
  tz = "America/Chicago"
)

# 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"
)

General Data Import from Water Quality Portal

Description

Imports data from Water Quality Portal web service. This function gets the data from here: https://www.waterqualitydata.us.

Usage

readWQPdata(
  ...,
  service = "Result",
  querySummary = FALSE,
  tz = "UTC",
  ignore_attributes = FALSE,
  convertType = TRUE
)

Arguments

Details

This function uses ... as a query input, which can be very flexible, but also has a steeper learning curve. For a quick overview, scroll down to the Examples in this help file to see many query options.

There are currently 10 legacy options for data provided by the Water Quality Portal:

Legacy:

There are 4 WQX3 options. These are still in-development, and should be used with caution.

Value

A data frame, the specific columns will depend on the "service" and/or "dataProfile".

There are also several useful attributes attached to the data frame:

Examples

# Legacy:
nameToUse <- "pH"
pHData <- readWQPdata(siteid = "USGS-04024315", 
                      characteristicName = nameToUse)
ncol(pHData)
attr(pHData, "siteInfo")
attr(pHData, "queryTime")
attr(pHData, "url")

# WQX3:
pHData_wqx3 <- readWQPdata(siteid = "USGS-04024315", 
                           characteristicName = nameToUse,
                           service = "ResultWQX3",
                           dataProfile = "basicPhysChem")
attr(pHData_wqx3, "url")

# More examples:
# querying by county
DeWitt <- readWQPdata(
  statecode = "Illinois",
  countycode = "DeWitt",
  characteristicName = "Nitrogen"
)

attr(DeWitt, "url")

DeWitt_wqx3 <- readWQPdata(
   statecode = "Illinois",
   countycode = "DeWitt",
   characteristicName = "Nitrogen",
   service = "ResultWQX3",
   dataProfile = "basicPhysChem",  
   ignore_attributes = TRUE)

attr(DeWitt_wqx3, "url")

# Data profile: "Sampling Activity"
activity <- readWQPdata(
  siteid = "USGS-04024315",
  service = "Activity"
)
attr(activity, "url")

# activity_wqx3 <- readWQPdata(
#   siteid = "USGS-04024315",
#   service = "ActivityWQX3"
# )
# attr(activity_wqx3, "url")

Dane_activity <- readWQPdata(
  statecode = "Wisconsin",
  countycode = "Dane",
  startDateLo = "2023-01-01",
  startDateHi = "2023-12-31",
  service = "Activity"
)
attr(Dane_activity, "url")

# Dane_activity_wqx3 <- readWQPdata(
#   statecode = "Wisconsin",
#   countycode = "Dane",
#   startDateLo = "2023-01-01",
#   startDateHi = "2023-12-31",
#   service = "ActivityWQX3"
# )
# attr(Dane_activity_wqx3, "url")

########################################################
# Additional examples:

 
# Data profiles: "Organization Data" 
org_data <- readWQPdata(
  statecode = "WI",
  countycode = "Dane",
  service = "Organization"
)

# Data profiles: "Project Data"  
project_data <- readWQPdata(
  statecode = "WI",
  countycode = "Dane",
  service = "Project"
)

# Data profiles: "Project Monitoring Location Weighting Data"
proj_mlwd <- readWQPdata(
  statecode = "WI",
  countycode = "Dane",
  service = "ProjectMonitoringLocationWeighting"
)

# Data profiles: "Sample Results (physical/chemical metadata)" 
samp_data <- readWQPdata(
  siteid = "USGS-04024315",
  dataProfile = "resultPhysChem",
  service = "Result"
)

# Data profiles: "Sample Results (biological metadata)"
samp_bio <- readWQPdata(
  siteid = "USGS-04024315",
  dataProfile = "biological",
  service = "Result"
)


# Data profiles: "Sample Results (narrow)" 
samp_narrow <- readWQPdata(
  siteid = "USGS-04024315",
  service = "Result",
  dataProfile = "narrowResult"
)

# samp_narrow_wqx3 <- readWQPdata(
#   siteid = "USGS-04024315",
#   service = "ResultWQX3",
#   dataProfile = "narrow"
# )


# Data profiles: "Sampling Activity"  
samp_activity <- readWQPdata(
  siteid = "USGS-04024315",
  dataProfile = "activityAll",
  service = "Activity"
)

# Data profile: "Sampling Activity Metrics"
act_metrics <- readWQPdata(
  statecode = "WI",
  countycode = "Dane",
  service = "ActivityMetric"
)

# Data profile: "Result Detection Quantitation Limit Data"  
dl_data <- readWQPdata(
  siteid = "USGS-04024315",
  service = "ResultDetectionQuantitationLimit"
)

# other options:
Phosphorus <- readWQPdata(
  statecode = "WI", countycode = "Dane", 
  characteristicName = "Phosphorus",
  startDateLo = "2023-01-01",
  ignore_attributes = TRUE,
  convertType = FALSE
)

rawPHsites_legacy <- readWQPdata(siteid = c("USGS-05406450", "USGS-05427949", "WIDNR_WQX-133040"),
                        characteristicName = "pH",
                        service = "Result",
                        dataProfile = "narrowResult" )

# rawPHsites <- readWQPdata(siteid = c("USGS-05406450", "USGS-05427949", "WIDNR_WQX-133040"),
#                           characteristicName = "pH",
#                           service = "ResultWQX3",
#                           dataProfile = "narrow" )

Format and organize WQP arguments that are passed in as ....

Description

Format and organize WQP arguments that are passed in as ....

Usage

readWQPdots(..., legacy = TRUE)

Raw Data Import for Water Quality Portal

Description

Imports data from the Water Quality Portal. This function gets the data from here: https://www.waterqualitydata.us. There are four required input arguments: siteNumbers, parameterCd, startDate, and endDate. parameterCd can either be a USGS 5-digit code, or a characteristic name. The sites can be either USGS, or other Water Quality Portal offered sites. It is required to use the 'full' site name, such as 'USGS-01234567'.

Usage

readWQPqw(
  siteNumbers,
  parameterCd,
  startDate = "",
  endDate = "",
  tz = "UTC",
  legacy = TRUE,
  querySummary = FALSE,
  ignore_attributes = FALSE,
  convertType = TRUE
)

Arguments

Value

A data frame derived from the default data profile.

There are also several useful attributes attached to the data frame:

See Also

readWQPdata(), whatWQPsites(), and importWQP()

Examples

rawPcode <- readWQPqw("USGS-01594440", "01075", "", "")

attr(rawPcode, "siteInfo")
attr(rawPcode, "queryTime")
attr(rawPcode, "url") 

rawCharacteristicName <- readWQPqw("WIDNR_WQX-10032762", "Specific conductance", "", "")
pHsites_legacy <- readWQPqw(c("USGS-05406450", "USGS-05427949", "WIDNR_WQX-133040"),
                        "pH", "", "")
ncol(pHsites_legacy)
attr(pHsites_legacy, "url")
 
# pHsites_modern <- readWQPqw(c("USGS-05406450", "USGS-05427949", "WIDNR_WQX-133040"),
#                         "pH", "", "", legacy = FALSE)
# ncol(pHsites_modern)
# attr(pHsites_modern, "url")
          
nwisEx <- readWQPqw("USGS-04024000", c("34247", "30234", "32104", "34220"), "", "2022-12-20")

DO <- readWQPqw(siteNumbers = "USGS-05288705", 
                parameterCd = "00300",
                convertType = FALSE)

Summary of Data Available from Water Quality Portal

Description

Returns a list of sites with year-by-year information on what data is available. The function gets the data from: https://www.waterqualitydata.us. Arguments to the function should be based on https://www.waterqualitydata.us/webservices_documentation. The information returned from this function describes the available data at the WQP sites, and some metadata on the sites themselves.

Usage

readWQPsummary(...)

Arguments

Value

A data frame from the data returned from the Water Quality Portal about the data available for the query parameters.

See Also

whatWQPsites whatWQPdata

Examples

# Summary of a single site for the last 5 years:
site_5 <- readWQPsummary(
  siteid = "USGS-07144100",
  summaryYears = 5
)

# Summary of a single site for the full period of record:
site_all <- readWQPsummary(
  siteid = "USGS-07144100",
  summaryYears = "all"
)

# Summary of the data available from streams in a single county:
dane_county_data <- readWQPsummary(
  countycode = "US:55:025",
  summaryYears = 5,
  siteType = "Stream"
)

# Summary of the data all available from lakes in a single county:
lake_sites <- readWQPsummary(
  siteType = "Lake, Reservoir, Impoundment",
  countycode = "US:55:025"
)

# Summary of the data available for the last 5 years in New Jersey:
state1 <- readWQPsummary(
  statecode = "NJ",
  summaryYears = 5,
  siteType = "Stream"
)

Generalized USGS Water Data API retrieval function

Description

Function that allows complex CQL queries. See https://api.waterdata.usgs.gov/docs/ogcapi/complex-queries/ for more information.

Usage

read_waterdata(service, CQL, ..., convertType = TRUE)

Arguments

Examples

cql <- '{
"op": "and",
"args": [
  {
    "op": "in",
    "args": [
      { "property": "parameter_code" },
      [ "00060", "00065" ]
    ]
  },
 {
    "op": "in",
    "args": [
      { "property": "monitoring_location_id" },
      [ "USGS-07367300", "USGS-03277200" ]
    ]
  }
]
}'

dv_data <- read_waterdata(service = "daily",
                          CQL = cql,
                          time = c("2023-01-01", "2024-01-01"))

# A wildcard in CQL2 is %
# Here's how to get HUCs that fall within 02070010
cql_huc_wildcard <- '{
"op": "like",
"args": [
  { "property": "hydrologic_unit_code" },
  "02070010%"
]
}'

what_huc_sites <- read_waterdata(service = "monitoring-locations",
                                 CQL = cql_huc_wildcard)               

Get USGS Daily Data

Description

Daily data provide one data value to represent water conditions for the day. Throughout much of the history of the USGS, the primary water data available was daily data collected manually at the monitoring location once each day. With improved availability of computer storage and automated transmission of data, the daily data published today are generally a statistical summary or metric of the continuous data collected each day, such as the daily mean, minimum, or maximum value. Daily data are automatically calculated from the continuous data of the same parameter code and are described by parameter code and a statistic code. These data have also been referred to as “daily values” or “DV”.

Usage

read_waterdata_daily(
  monitoring_location_id = NA_character_,
  parameter_code = NA_character_,
  statistic_id = NA_character_,
  properties = NA_character_,
  time_series_id = NA_character_,
  daily_id = NA_character_,
  approval_status = NA_character_,
  unit_of_measure = NA_character_,
  qualifier = NA_character_,
  value = NA,
  last_modified = NA_character_,
  skipGeometry = NA,
  time = NA_character_,
  bbox = NA,
  limit = NA,
  max_results = NA,
  convertType = TRUE
)

Arguments

Examples

site <- "USGS-02238500"
pcode <- "00060"
dv_data_sf <- read_waterdata_daily(monitoring_location_id = site,
                              parameter_code = "00060", 
                              time = c("2021-01-01", "2022-01-01"))
                              
dv_data_last_modified <- read_waterdata_daily(monitoring_location_id = site,
                              parameter_code = "00060",
                              last_modified = "P7D")

dv_data_trim <- read_waterdata_daily(monitoring_location_id = site,
                          parameter_code = "00060", 
                          properties = c("monitoring_location_id",
                                         "value",
                                         "time"),
                          time = c("2021-01-01", "2022-01-01"))

dv_data <- read_waterdata_daily(monitoring_location_id = site,
                           parameter_code = "00060",
                           skipGeometry = TRUE)
                        
dv_data_period <- read_waterdata_daily(monitoring_location_id = site,
                                  parameter_code = "00060",
                                  time = "P7D")

multi_site <- read_waterdata_daily(monitoring_location_id =  c("USGS-01491000",
                                                          "USGS-01645000"),
                              parameter_code = c("00060", "00010"),
                              limit = 500,
                              time = c("2023-01-01", "2024-01-01"))

Get Latest Continuous USGS Water Data

Description

This endpoint provides the most recent observation for each time series of continuous data. Continuous data are collected via automated sensors installed at a monitoring location. They are collected at a high frequency and often at a fixed 15-minute interval. Depending on the specific monitoring location, the data may be transmitted automatically via telemetry and be available on WDFN within minutes of collection, while other times the delivery of data may be delayed if the monitoring location does not have the capacity to automatically transmit data. Continuous data are described by parameter name and parameter code. These data might also be referred to as "instantaneous values" or "IV"

Usage

read_waterdata_latest_continuous(
  monitoring_location_id = NA_character_,
  parameter_code = NA_character_,
  statistic_id = NA_character_,
  properties = NA_character_,
  time_series_id = NA_character_,
  latest_continuous_id = NA_character_,
  approval_status = NA_character_,
  unit_of_measure = NA_character_,
  qualifier = NA_character_,
  value = NA,
  last_modified = NA_character_,
  skipGeometry = NA,
  time = NA_character_,
  bbox = NA,
  limit = NA,
  max_results = NA,
  convertType = TRUE
)

Arguments

Examples

site <- "USGS-451605097071701"
pcode <- "72019"
uv_data_sf <- read_waterdata_latest_continuous(monitoring_location_id = site,
                              parameter_code = pcode)

uv_data_trim <- read_waterdata_latest_continuous(monitoring_location_id = site,
                          parameter_code = pcode, 
                          properties = c("monitoring_location_id",
                                         "value",
                                         "time"))

uv_data <- read_waterdata_latest_continuous(monitoring_location_id = site,
                           parameter_code = pcode,
                           skipGeometry = TRUE)
                        
uv_data_period <- read_waterdata_latest_continuous(monitoring_location_id = site,
                                  parameter_code = pcode,
                                  time = "P7D")

multi_site <- read_waterdata_latest_continuous(monitoring_location_id =  c("USGS-451605097071701",
                                                          "USGS-14181500"),
                              parameter_code = c("00060", "72019"),
                              skipGeometry = TRUE)

# Only return data that has been modified in last 7 days         
multi_site2 <- read_waterdata_latest_continuous(monitoring_location_id =  c("USGS-451605097071701",
                                                                           "USGS-14181500"),
                                               parameter_code = c("00060", "72019"),
                                               last_modified = "P7D")

Generalized USGS Water Meta Data API retrieval function

Description

Function to get metadata from Water Data API. These are useful to get the human readable words and other metadata associated with USGS codes.

Usage

read_waterdata_metadata(collection, max_results = NA, limit = NA)

Arguments

Examples

agency_codes <- read_waterdata_metadata("agency-codes")
altitude_datums <- read_waterdata_metadata("altitude-datums")
aquifer_codes <- read_waterdata_metadata("aquifer-codes")
aquifer_types <- read_waterdata_metadata("aquifer-types")
coordinate_accuracy_codes <- read_waterdata_metadata("coordinate-accuracy-codes")
coordinate_datum_codes <- read_waterdata_metadata("coordinate-datum-codes")
coordinate_method_codes <- read_waterdata_metadata("coordinate-method-codes")
national_aquifer_codes <- read_waterdata_metadata("national-aquifer-codes")
parameter_codes <- read_waterdata_metadata("parameter-codes")
reliability_codes <- read_waterdata_metadata("reliability-codes")
site_types <- read_waterdata_metadata("site-types")
statistic_codes <- read_waterdata_metadata("statistic-codes")
topographic_codes <- read_waterdata_metadata("topographic-codes")
time_zone_codes <- read_waterdata_metadata("time-zone-codes")

Get USGS Site Data

Description

Location information is basic information about the monitoring location including the name, identifier, agency responsible for data collection, and the date the location was established. It also includes information about the type of location, such as stream, lake, or groundwater, and geographic information about the location, such as state, county, latitude and longitude, and hydrologic unit code (HUC).

Usage

read_waterdata_monitoring_location(
  monitoring_location_id = NA_character_,
  agency_code = NA_character_,
  agency_name = NA_character_,
  monitoring_location_number = NA_character_,
  monitoring_location_name = NA_character_,
  district_code = NA_character_,
  country_code = NA_character_,
  country_name = NA_character_,
  state_code = NA_character_,
  state_name = NA_character_,
  county_code = NA_character_,
  county_name = NA_character_,
  minor_civil_division_code = NA_character_,
  site_type_code = NA_character_,
  site_type = NA_character_,
  hydrologic_unit_code = NA_character_,
  basin_code = NA_character_,
  altitude = NA_character_,
  altitude_accuracy = NA_character_,
  altitude_method_code = NA_character_,
  altitude_method_name = NA_character_,
  vertical_datum = NA_character_,
  vertical_datum_name = NA_character_,
  horizontal_positional_accuracy_code = NA_character_,
  horizontal_positional_accuracy = NA_character_,
  horizontal_position_method_code = NA_character_,
  horizontal_position_method_name = NA_character_,
  original_horizontal_datum = NA_character_,
  original_horizontal_datum_name = NA_character_,
  drainage_area = NA_character_,
  contributing_drainage_area = NA_character_,
  time_zone_abbreviation = NA_character_,
  uses_daylight_savings = NA_character_,
  construction_date = NA_character_,
  aquifer_code = NA_character_,
  national_aquifer_code = NA_character_,
  aquifer_type_code = NA_character_,
  well_constructed_depth = NA_character_,
  hole_constructed_depth = NA_character_,
  depth_source_code = NA_character_,
  properties = NA_character_,
  bbox = NA,
  limit = NA,
  max_results = NA,
  skipGeometry = NA
)

Arguments

Examples

site <- "USGS-02238500"
site_info <- read_waterdata_monitoring_location(monitoring_location_id = site)

site_slim <- read_waterdata_monitoring_location(
                             monitoring_location_id = c("USGS-05114000",
                                                        "USGS-09423350"),
                             properties = c("monitoring_location_id",
                                            "state_name",
                                            "country_name"))
                                            
site_slim_no_sf_slim <- read_waterdata_monitoring_location(monitoring_location_id = site,
                                           properties = c("monitoring_location_id",
                                                          "state_name",
                                                          "country_name"), 
                                           skipGeometry = TRUE)

site_info_no_sf <- read_waterdata_monitoring_location(monitoring_location_id = site,
                                   skipGeometry = TRUE)

bbox_vals = c(-94.00, 35.0, -93.5, 35.5)
multi_site <- read_waterdata_monitoring_location(bbox = bbox_vals)
multi_site_n_100 <- read_waterdata_monitoring_location(bbox = bbox_vals,
                                                  max_results = 100)
multi_site_limit_100 <- read_waterdata_monitoring_location(bbox = bbox_vals,
                                                      limit = 100)

Get USGS Parameter Code Information

Description

Parameter codes are 5-digit codes and associated descriptions used to identify the constituent measured and the units of measure. Some parameter code definitions include information about the sampling matrix, fraction, and methods used to measure the constituent. Some parameters are fixed-value (fxd) numeric codes having textual meaning (for example: parameter code 00041 is a weather code parameter, code of 60 means rain), but more commonly represent a numeric value for chemical, physical, or biological data.

Usage

read_waterdata_parameter_codes(
  parameter_code = NA_character_,
  parameter_name = NA_character_,
  unit_of_measure = NA_character_,
  parameter_group_code = NA_character_,
  parameter_description = NA_character_,
  medium = NA_character_,
  statistical_basis = NA_character_,
  weight_basis = NA_character_,
  sample_fraction = NA_character_,
  temperature_basis = NA_character_,
  epa_equivalence = NA_character_,
  properties = NA_character_,
  limit = NA,
  max_results = NA
)

Arguments

Examples

pcode <- "00060"
pcode_info <- read_waterdata_parameter_codes(parameter_code = pcode)

pcodes <- read_waterdata_parameter_codes(parameter_code = c("00660", "00060"))

# equivalent to read_waterdata_metadata("parameter-codes")
all_pcodes <- read_waterdata_parameter_codes() 

total_nutrients <- read_waterdata_parameter_codes(parameter_group_code = "NUT",
                                           sample_fraction = "Total")
                                           
group_of_nutrients <- read_waterdata_parameter_codes(parameter_group_code = "NUT",
                                                    unit_of_measure = c("mg/l",
                                                    "mg/l as N", "mg/l NO3",
                                                    "mg/l asNO2"))

USGS Samples Data

Description

This function creates the call and gets the data for discrete water quality samples data service described at https://waterdata.usgs.gov/download-samples/.

Usage

read_waterdata_samples(
  monitoringLocationIdentifier = NA,
  siteTypeCode = NA,
  boundingBox = NA,
  hydrologicUnit = NA,
  activityMediaName = NA,
  characteristicGroup = NA,
  characteristic = NA,
  characteristicUserSupplied = NA,
  activityStartDateLower = NA,
  activityStartDateUpper = NA,
  countryFips = NA,
  stateFips = NA,
  countyFips = NA,
  projectIdentifier = NA,
  recordIdentifierUserSupplied = NA,
  siteTypeName = NA,
  usgsPCode = NA,
  pointLocationLatitude = NA,
  pointLocationLongitude = NA,
  pointLocationWithinMiles = NA,
  dataType = "results",
  dataProfile = NA,
  tz = "UTC",
  convertType = TRUE
)

read_USGS_samples(
  monitoringLocationIdentifier = NA,
  siteTypeCode = NA,
  boundingBox = NA,
  hydrologicUnit = NA,
  activityMediaName = NA,
  characteristicGroup = NA,
  characteristic = NA,
  characteristicUserSupplied = NA,
  activityStartDateLower = NA,
  activityStartDateUpper = NA,
  countryFips = NA,
  stateFips = NA,
  countyFips = NA,
  projectIdentifier = NA,
  recordIdentifierUserSupplied = NA,
  siteTypeName = NA,
  usgsPCode = NA,
  pointLocationLatitude = NA,
  pointLocationLongitude = NA,
  pointLocationWithinMiles = NA,
  dataType = "results",
  dataProfile = NA,
  tz = "UTC",
  convertType = TRUE
)

Arguments

Examples

ph_data <- read_waterdata_samples(
               monitoringLocationIdentifier = "USGS-04074950",
               characteristicUserSupplied = "pH, water, unfiltered, field",
               activityStartDateUpper = "2000-01-01",
               dataProfile = "narrow")
               
nameToUse <- "pH"
pHData <- read_waterdata_samples(monitoringLocationIdentifier = "USGS-04024315", 
                         characteristic = nameToUse)
ncol(pHData)
attr(pHData, "url")
attr(pHData, "queryTime")

summary_data <- read_waterdata_samples(monitoringLocationIdentifier = "USGS-04024315", 
                               dataType = "projects")

Get USGS Time Series Metadata

Description

Daily data and continuous measurements are grouped into time series, which represent a collection of observations of a single parameter, potentially aggregated using a standard statistic, at a single monitoring location. This endpoint provides metadata about those time series, including their operational thresholds, units of measurement, and when the earliest and most recent observations in a time series occurred.

Usage

read_waterdata_ts_meta(
  monitoring_location_id = NA_character_,
  parameter_code = NA_character_,
  parameter_name = NA_character_,
  properties = NA_character_,
  statistic_id = NA_character_,
  last_modified = NA_character_,
  begin = NA_character_,
  end = NA_character_,
  unit_of_measure = NA_character_,
  computation_period_identifier = NA_character_,
  computation_identifier = NA_character_,
  thresholds = NA,
  sublocation_identifier = NA_character_,
  primary = NA_character_,
  time_series_id = NA_character_,
  web_description = NA_character_,
  skipGeometry = NA,
  limit = NA,
  max_results = NA,
  bbox = NA,
  convertType = FALSE
)

Arguments

Examples

site <- "USGS-02238500"
meta_1 <- read_waterdata_ts_meta(monitoring_location_id = site)

meta_multi <- read_waterdata_ts_meta(monitoring_location_id =  c("USGS-01491000", 
                                                            "USGS-01645000"),
                            parameter_code = c("00060", "00010"),
                            properties = c("monitoring_location_id",
                                           "parameter_code",
                                           "begin",
                                           "end",
                                           "time_series_id"),
                            skipGeometry = TRUE)

renameColumns

Description

Rename columns coming back from NWIS data retrievals. Daily and unit value columns have names derived from their data descriptor, parameter, and statistic codes. This function reads information from the header and the arguments in the call to to rename those columns.

Usage

renameNWISColumns(
  rawData,
  p00010 = "Wtemp",
  p00045 = "Precip",
  p00060 = "Flow",
  p00065 = "GH",
  p00095 = "SpecCond",
  p00300 = "DO",
  p00400 = "pH",
  p62611 = "GWL",
  p63680 = "Turb",
  p72019 = "WLBLS",
  ...
)

Arguments

Value

A dataset like data with selected columns renamed.

Note

The following statistics codes are converted by renameNWISColumns.

00000

Instantaneous Value, suffix: Inst

00001

Maximum value, suffix: Max

00002

Minimum value, suffix: Min

00003

Mean value, no suffix

00006

Sum of values, suffix: Sum

00007

Modal value, suffix: Mode

00008

Median value, suffix: Median

00012

Equivalent mean value, suffix: EqMean

00021

Tidal high-high value, suffix: HiHiTide

00022

Tidal low-high value, suffix: LoHiTide

00023

Tidal high-low value, suffix: HiLoTide

00024

Tidal low-low value, suffix: LoLoTide

See Also

readNWISdv(), readNWISuv()

Examples

siteWithTwo <- "01480015"
startDate <- "2012-09-01"
endDate <- "2012-10-01"

twoResults <- readNWISdv(siteWithTwo, "00060", startDate, endDate)
names(twoResults)
renamedCols <- renameNWISColumns(twoResults)
names(renamedCols)
# Custom names:
newNames <- renameNWISColumns(twoResults, p00060 = "Discharge")
names(newNames)

Set data endpoint

Description

access Indicate which dataRetrieval access code you want to use options: c('public','internal')

Usage

setAccess(access = "public")

Arguments

Author(s)

Luke Winslow, Jordan S Read

Examples

setAccess("internal")

setAccess("public")

US State Code Lookup Table

Description

Classic lookup table for states. Has been replaced in functions with check_waterdata_sample_params("states").

Value

stateCd data frame.

Examples

head(stateCd)

State code look up

Description

Function to simplify finding state and state code definitions. Used in readNWISdata and readWQPdata.

Usage

stateCdLookup(input, outputType = "postal", country = "US")

Arguments

Examples

fullName <- stateCdLookup("wi", "fullName")
abbriev <- stateCdLookup("Wisconsin", "postal")
id <- stateCdLookup("WI", "id")
name <- stateCdLookup(55, "fullName")
fips <- stateCdLookup("WI", "fips")
canada_st <- stateCdLookup(13, "fullName", country = "CA")
mexico_st <- stateCdLookup(13, "fullName", country = "MX")
stateCdLookup(c("West Virginia", "Wisconsin", 200, 55, "MN"))

USGS Samples Summary Data

Description

This function creates the call and gets the data for discrete water quality samples summary data service described at https://api.waterdata.usgs.gov/samples-data/docs.

Usage

summarize_waterdata_samples(monitoringLocationIdentifier)

summarize_USGS_samples(monitoringLocationIdentifier)

Arguments

Value

data frame with summary of data available based on the monitoringLocationIdentifier

Examples

monitoringLocationIdentifier <- "USGS-04074950"

what_data <- summarize_waterdata_samples(monitoringLocationIdentifier)

USGS data availability

Description

Imports a table of available parameters, period of record, and count. See https://waterservices.usgs.gov/docs/site-service/ for more information.

Usage

whatNWISdata(..., convertType = TRUE)

Arguments

Details

This function requires users to create their own arguments based on the NWIS web services. It is a more complicated function to use compared to other NWIS functions such as readNWISdv(), readNWISuv(), etc. However, this function adds a lot of flexibility to the possible queries. If the "service" argument is included, the results will be filtered to the proper data_type_cd. This is a great function to use before a large data set, by filtering down the number of sites that have useful data.

Value

A data frame with the following columns:

There are also several useful attributes attached to the data frame:

See Also

read_waterdata_ts_meta()

Examples

# see ?read_waterdata_ts_meta

#site1 <- whatWQPsamples(siteid = "USGS-01594440")

#type <- "Stream"

#sites <- whatWQPsamples(countycode = "US:55:025", siteType = type)

#lakeSites_samples <- whatWQPsamples(siteType = "Lake, Reservoir, Impoundment",
#                                    countycode = "US:55:025")

Site Data Import from NWIS

Description

Returns a list of sites from the NWIS web service. This function gets the data from: https://waterservices.usgs.gov/docs/site-service/. Mapper format is used

Usage

whatNWISsites(...)

Arguments

Value

A data frame with at least the following columns:

There are also several useful attributes attached to the data frame:

See Also

read_waterdata_monitoring_location()

Examples

# see ?read_waterdata_monitoring_location
#siteListPhos <- whatNWISsites(stateCd = "OH", parameterCd = "00665")
#oneSite <- whatNWISsites(sites = "05114000")

Data Available from Water Quality Portal

Description

Returns a list of sites from the Water Quality Portal web service. This function gets the data from: https://www.waterqualitydata.us. Arguments to the function should be based on https://www.waterqualitydata.us/webservices_documentation. The information returned from whatWQPdata describes the available data at the WQP sites, and some metadata on the sites themselves. For example, a row is returned for each individual site that fulfills this query. In that we can learn how many sampling activities and results are available for the query. It does not break those results down by any finer grain. For example, if you ask for "Nutrients" (characteristicGroup), you will not learn what specific nutrients are available at that site. For that kind of data discovery see readWQPsummary.

Usage

whatWQPdata(..., convertType = TRUE)

Arguments

Value

A data frame that returns basic data availability such as sites, number of results, and number of sampling activities from the query parameters for the Water Quality Portal.

See Also

whatWQPsites readWQPsummary readWQPdata

Examples

site1 <- whatWQPdata(siteid = "USGS-01594440")

type <- "Stream"
sites <- whatWQPdata(countycode = "US:55:025", siteType = type)

lakeSites <- whatWQPdata(siteType = "Lake, Reservoir, Impoundment",
                         countycode = "US:55:025")
lakeSites_chars <- whatWQPdata(
  siteType = "Lake, Reservoir, Impoundment",
  countycode = "US:55:025", convertType = FALSE)


bbox <- c(-86.9736, 34.4883, -86.6135, 34.6562)
what_bb <- whatWQPdata(bBox = bbox)

Site Data Import from Water Quality Portal

Description

Returns a list of sites from the Water Quality Portal web service. This function gets the data from: https://www.waterqualitydata.us. Arguments to the function should be based on https://www.waterqualitydata.us/webservices_documentation. The return from this function returns the basic metadata on WQP sites. It is generally faster than the whatWQPdata() function, but does not return information on what data was collected at the site.

Usage

whatWQPsamples(..., convertType = TRUE, legacy = TRUE)

whatWQPmetrics(..., convertType = TRUE)

whatWQPsites(..., legacy = TRUE, convertType = TRUE)

Arguments

Value

A data frame with information on the sampling activity available from the Water Quality Portal for the query parameters.

data frame that includes information on site metadata.

See Also

whatWQPdata readWQPsummary

whatNWISdata

Examples

site1 <- whatWQPsamples(siteid = "USGS-01594440")

type <- "Stream"

sites <- whatWQPsamples(countycode = "US:55:025", siteType = type)

lakeSites_samples <- whatWQPsamples(siteType = "Lake, Reservoir, Impoundment",
                                    countycode = "US:55:025")



type <- "Stream"

sites <- whatWQPmetrics(countycode = "US:55:025", siteType = type)
lakeSites_metrics <- whatWQPmetrics(siteType = "Lake, Reservoir, Impoundment",
                                    countycode = "US:55:025")




site1 <- whatWQPsites(siteid = "USGS-01594440")

type <- "Stream"
sites <- whatWQPsites(
  countycode = "US:55:025",
  characteristicName = "Phosphorus",
  siteType = type
)

Get WQP service metadata

Description

The information from this request is only available for a limited time after the original query from the WQP. In the readWQPdata and readWQPqw functions, the results from this function will be attached as an attribute to the data.

Usage

wqp_check_status(wqp_request_id)

Arguments

Value

a list generated from the WQP describing what data was returned.

Examples

rawPcode <- readWQPqw("USGS-01594440", "01075", 
                      ignore_attributes = TRUE, legacy = FALSE)
headerInfo <- attr(rawPcode, "headerInfo")
wqp_request_id <- headerInfo$`wqp-request-id`
count_info <- wqp_check_status(wqp_request_id)
count_info[["dataProviders"]]

Pad string with leading zeros

Description

Function to pad a string with leading zeros. Useful for parameter codes and USGS site IDs.

Usage

zeroPad(x, padTo)

Arguments

Value

x character returned with leading zeros

Examples

pCode <- "10"
correctPCode <- zeroPad(pCode, 5)
pCodes <- c("100", "1000", "0", "12345", "1565465465465465")
correctPCodes <- zeroPad(pCodes, 5)
pCodeNA <- c(1, 2, NA)
padPCodeNA <- zeroPad(pCodeNA, 4)