From 2f1308def0e5b47272e3bab432e98c70287ee3a8 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Fri, 28 Aug 2026 13:58:00 -0500 Subject: [PATCH 01/11] Switch to v1 --- DESCRIPTION | 2 +- NAMESPACE | 20 ++++---- R/AAA.R | 5 +- R/read_waterdata_field_measurements.R | 2 +- R/read_waterdata_ts_meta.R | 48 ++++++++++++++++-- R/walk_pages.R | 63 ++++++++++++------------ man/read_waterdata_field_measurements.Rd | 2 +- man/read_waterdata_ts_meta.Rd | 57 ++++++++++----------- 8 files changed, 121 insertions(+), 78 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index dba89ba8..db12e454 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -72,4 +72,4 @@ BuildVignettes: true VignetteBuilder: knitr BugReports: https://github.com/DOI-USGS/dataRetrieval/issues Roxygen: list(markdown = TRUE) -Config/roxygen2/version: 8.0.0 +Config/roxygen2/version: 8.1.0 diff --git a/NAMESPACE b/NAMESPACE index 002c070f..c68d3c96 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -80,12 +80,14 @@ export(whatWQPsamples) export(whatWQPsites) export(wqp_check_status) export(zeroPad) -importFrom(data.table,":=") -importFrom(data.table,.BY) -importFrom(data.table,.EACHI) -importFrom(data.table,.GRP) -importFrom(data.table,.I) -importFrom(data.table,.N) -importFrom(data.table,.NGRP) -importFrom(data.table,.SD) -importFrom(data.table,data.table) +importFrom(data.table, + ":=", + .BY, + .EACHI, + .GRP, + .I, + .N, + .NGRP, + .SD, + data.table +) diff --git a/R/AAA.R b/R/AAA.R index 1cd88cad..6c2f8833 100644 --- a/R/AAA.R +++ b/R/AAA.R @@ -6,7 +6,7 @@ pkg.env <- new.env() options( "dataRetrieval.nldi_base" = "https://api.water.usgs.gov/nldi/linked-data/" ) - options("dataRetrieval.api_version" = "v0") + options("dataRetrieval.api_version" = "v1") options("dataRetrieval.api_version_stat" = "v0") options("dataRetrieval.attach_request" = TRUE) options("dataRetrieval.convertType" = TRUE) @@ -138,8 +138,7 @@ https://doi-usgs.github.io/dataRetrieval/articles/Status.html" new_nwis_message <- function() { return( - "ALERT: All NWIS services are slated for decommission -and new dataRetrieval functions will be added. + "ALERT: All NWIS services are slated for decommission in early 2027. For up-to-date information, see: https://doi-usgs.github.io/dataRetrieval/articles/Status.html" ) diff --git a/R/read_waterdata_field_measurements.R b/R/read_waterdata_field_measurements.R index 166da199..7bea3fc8 100644 --- a/R/read_waterdata_field_measurements.R +++ b/R/read_waterdata_field_measurements.R @@ -51,7 +51,7 @@ #' @examplesIf is_dataRetrieval_user() #' #' \donttest{ -#' site <- "USGS-02238500" +#' site <- "USGS-14202650" #' field_data_sf <- read_waterdata_field_measurements(monitoring_location_id = site) #' #' groundwater <- read_waterdata_field_measurements(monitoring_location_id = "USGS-375907091432201") diff --git a/R/read_waterdata_ts_meta.R b/R/read_waterdata_ts_meta.R index 0b06a704..22b48789 100644 --- a/R/read_waterdata_ts_meta.R +++ b/R/read_waterdata_ts_meta.R @@ -18,14 +18,16 @@ #' @param last_modified `r get_ogc_params("time-series-metadata")$last_modified` #' #' See also Details below for more information. -#' @param begin_utc `r get_ogc_params("time-series-metadata")$begin_utc` +#' @param begin_utc Deprecated in v1. Use "begin" instead. #' #' #' See also Details below for more information. -#' @param end_utc `r get_ogc_params("time-series-metadata")$end_utc` +#' @param end_utc Deprecated in v1. Use "end" instead. #' #' See also Details below for more information. -#' @param hydrologic_unit_code `r get_ogc_params("time-series-metadata")$hydrologic_unit_code` -#' @param state_name `r get_ogc_params("time-series-metadata")$state_name` +#' @param hydrologic_unit_code Deprecated in v1. Use `read_waterdata_combined_meta` for +#' similar functionality. +#' @param state_name Deprecated in v1. Use `read_waterdata_combined_meta` for +#' similar functionality. #' @param thresholds `r get_ogc_params("time-series-metadata")$thresholds` #' @param unit_of_measure `r get_ogc_params("time-series-metadata")$unit_of_measure` #' @param primary @@ -105,6 +107,44 @@ read_waterdata_ts_meta <- function( output_id <- "time_series_id" rlang::check_dots_empty() + on.exit(options("dataRetrieval.api_version" = "v1")) + + if (!is.na(state_name)) { + warning( + "state_name is deprecated starting in v1 of the Water Data APIs. +Use the function read_waterdata_combined_meta instead. +Reverting to v0 version of Water Data APIs." + ) + options("dataRetrieval.api_version" = "v0") + } + + if (!is.na(hydrologic_unit_code)) { + warning( + "hydrologic_unit_code is deprecated starting in v1 of the Water Data APIs. +Use the function read_waterdata_combined_meta instead. +Reverting to v0 version of Water Data APIs." + ) + options("dataRetrieval.api_version" = "v0") + } + + if (!is.na(begin_utc)) { + warning( + "begin_utc is deprecated starting in v1 of the Water Data APIs. +Use begin instead. +Reverting to v0 version of Water Data APIs." + ) + options("dataRetrieval.api_version" = "v0") + } + + if (!is.na(end_utc)) { + warning( + "end_utc is deprecated starting in v1 of the Water Data APIs. +Use end instead. +Reverting to v0 version of Water Data APIs." + ) + options("dataRetrieval.api_version" = "v0") + } + args <- mget(names(formals())) return_list <- get_ogc_data(args, output_id, service) diff --git a/R/walk_pages.R b/R/walk_pages.R index 1d4f63f1..0d73cb86 100644 --- a/R/walk_pages.R +++ b/R/walk_pages.R @@ -11,13 +11,13 @@ walk_pages <- function(req) { max_reqs = Inf, on_error = "stop" ) - + failures <- resps |> httr2::resps_failures() - + return_list <- resps |> httr2::resps_successes() |> httr2::resps_data(\(resp) get_resp_data(resp)) - + return(return_list) } @@ -34,30 +34,30 @@ walk_pages <- function(req) { get_resp_data <- function(resp) { body <- httr2::resp_body_json(resp) use_sf <- !grepl("skipGeometry=true", resp$url, ignore.case = TRUE) - + if (isTRUE(body[["numberReturned"]] == 0)) { return(data.frame()) } - + return_df <- sf::read_sf(httr2::resp_body_string(resp)) - + return_df <- coerce_num_cols(return_df, is_sf = TRUE) - + return_df <- coerce_time_cols(return_df, is_sf = TRUE) - + return_df <- coerce_qualifier_cols(return_df, is_sf = TRUE) - + if ("altitude_accuracy" %in% names(return_df)) { return_df$altitude_accuracy <- as.character(return_df$altitude_accuracy) } - + if (!use_sf) { return_df <- sf::st_drop_geometry(return_df) if ("AsGeoJSON(geometry)" %in% names(return_df)) { return_df <- return_df[, !names(return_df) %in% "AsGeoJSON(geometry)"] } } - + return(return_df) } @@ -74,24 +74,24 @@ get_resp_data <- function(resp) { #' next_req_url <- function(resp, req) { body <- httr2::resp_body_json(resp) - + if (isTRUE(body[["code"]] == "InvalidQuery")) { message(body[["description"]]) return(NULL) } - + if (isTRUE(body[["numberReturned"]] == 0)) { return(NULL) } - + log_rate_limit(resp) if ("links" %in% names(body)) { links <- body$links if (any(sapply(links, function(x) x$rel) == "next")) { next_index <- which(sapply(links, function(x) x$rel) == "next") - + next_url <- links[[next_index]][["href"]] - + return(httr2::req_url(req = req, url = next_url)) } } else if (!is.null(body[["next"]])) { @@ -105,9 +105,9 @@ next_req_url <- function(resp, req) { get_csv <- function(req, limit) { skip_geo <- grepl("skipGeometry=true", req$url, ignore.case = TRUE) resp <- httr2::req_perform(req) - + log_rate_limit(resp) - + if (httr2::resp_has_body(resp)) { return_list <- httr2::resp_body_string(resp) df <- data.table::fread( @@ -115,11 +115,11 @@ get_csv <- function(req, limit) { data.table = FALSE, colClasses = "character" ) - + df <- coerce_num_cols(df, is_sf = FALSE) - + df <- coerce_time_cols(df, is_sf = FALSE) - + if (skip_geo) { df <- df[, names(df)[!names(df) %in% c("x", "y")]] } else { @@ -128,7 +128,7 @@ get_csv <- function(req, limit) { sf::st_crs(df) <- 4269 } } - + if (nrow(df) == limit) { warning( "Missing data is probable. Use no_paging = FALSE to @@ -138,12 +138,11 @@ ensure all requested data is returned." } else { df <- data.frame() } - + return(df) } -coerce_qualifier_cols <- function(df, is_sf = FALSE){ - +coerce_qualifier_cols <- function(df, is_sf = FALSE) { if ("qualifier" %in% names(df)) { df$qualifier <- as.character(vapply( X = df$qualifier, @@ -157,20 +156,22 @@ coerce_qualifier_cols <- function(df, is_sf = FALSE){ return(df) } -coerce_time_cols <- function(df, is_sf = FALSE){ +coerce_time_cols <- function(df, is_sf = FALSE) { included_time_cols <- names(df)[names(df) %in% time_periods] if (length(included_time_cols) == 0) { return(df) } - + check_df <- if (is_sf) { sf::st_drop_geometry(df[, included_time_cols, drop = FALSE]) } else { df[, included_time_cols, drop = FALSE] } - + if (any(vapply(check_df, is.character, TRUE))) { - df[, included_time_cols] <- lapply(check_df, function(x) as.POSIXct(x, tz = "UTC")) + df[, included_time_cols] <- lapply(check_df, function(x) { + as.POSIXct(x, tz = "UTC") + }) } return(df) } @@ -180,13 +181,13 @@ coerce_num_cols <- function(df, is_sf = FALSE) { if (length(included_num_cols) == 0) { return(df) } - + check_df <- if (is_sf) { sf::st_drop_geometry(df[, included_num_cols, drop = FALSE]) } else { df[, included_num_cols, drop = FALSE] } - + if (!all(vapply(check_df, is.numeric, logical(1)))) { df[, included_num_cols] <- lapply(check_df, as.numeric) } diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index 2565e2dc..707d73b2 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -173,7 +173,7 @@ daily data, which returns time values in local dates. \dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} \donttest{ -site <- "USGS-02238500" +site <- "USGS-14202650" field_data_sf <- read_waterdata_field_measurements(monitoring_location_id = site) groundwater <- read_waterdata_field_measurements(monitoring_location_id = "USGS-375907091432201") diff --git a/man/read_waterdata_ts_meta.Rd b/man/read_waterdata_ts_meta.Rd index fd381a2f..23d52d18 100644 --- a/man/read_waterdata_ts_meta.Rd +++ b/man/read_waterdata_ts_meta.Rd @@ -49,7 +49,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, time_series_id, unit_of_measure, parameter_name, parameter_code, statistic_id, hydrologic_unit_code, state_name, last_modified, begin, end, begin_utc, end_utc, computation_period_identifier, computation_identifier, thresholds, sublocation_identifier, primary, monitoring_location_id, web_description, parameter_description, parent_time_series_id, data_gap_interval. +geometry, time_series_id, unit_of_measure, parameter_name, parameter_code, statistic_id, last_modified, begin, end, computation_period_identifier, computation_identifier, thresholds, sublocation_identifier, primary, monitoring_location_id, web_description, parameter_description, parent_time_series_id, data_gap_interval. The default (\code{NA}) will return all columns of the data.} \item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/statistic-codes/items}. @@ -70,38 +70,19 @@ Only features that have a \code{last_modified} that intersects the value of date See also Details below for more information.} -\item{begin_utc}{The datetime of the earliest observation in the time series. Together with \code{end_utc}, this field represents the period of record of a time series. Note that some time series may have large gaps in their collection record. -You can query this field using date-times or intervals, adhering to RFC 3339, or using ISO 8601 duration objects. Intervals may be bounded or half-bounded (double-dots at start or end). -Examples: -\itemize{ -\item A date-time: "2018-02-12T23:20:50Z" -\item A bounded interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" -\item Half-bounded intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z" -\item Duration objects: "P1M" for data from the past month or "PT36H" for the last 36 hours -} - -Only features that have a \code{begin_utc} that intersects the value of datetime are selected. - +\item{begin_utc}{Deprecated in v1. Use "begin" instead. #' See also Details below for more information.} -\item{end_utc}{The datetime of the most recent observation in the time series. Data returned by this endpoint updates at most once per day, and potentially less frequently than that, and as such there may be more recent observations within a time series than the time series \code{end_utc} value reflects. Together with \code{begin_utc}, this field represents the period of record of a time series. It is additionally used to determine whether a time series is "active". -You can query this field using date-times or intervals, adhering to RFC 3339, or using ISO 8601 duration objects. Intervals may be bounded or half-bounded (double-dots at start or end). -Examples: -\itemize{ -\item A date-time: "2018-02-12T23:20:50Z" -\item A bounded interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" -\item Half-bounded intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z" -\item Duration objects: "P1M" for data from the past month or "PT36H" for the last 36 hours -} - -Only features that have a \code{end_utc} that intersects the value of datetime are selected. +\item{end_utc}{Deprecated in v1. Use "end" instead. See also Details below for more information.} -\item{hydrologic_unit_code}{The hydrologic unit code (HUC) for the monitoring location. Supports prefix matching — querying with a shorter HUC (e.g. "04") matches all locations within that hydrologic region.} +\item{hydrologic_unit_code}{Deprecated in v1. Use \code{read_waterdata_combined_meta} for +similar functionality.} -\item{state_name}{The name of the state or state equivalent in which the monitoring location is located.} +\item{state_name}{Deprecated in v1. Use \code{read_waterdata_combined_meta} for +similar functionality.} \item{unit_of_measure}{A human-readable description of the units of measurement associated with an observation.} @@ -141,9 +122,29 @@ vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, Southern-most latitude, Eastern-most longitude, Northern-most longitude).} -\item{begin}{This field contains the same information as "begin_utc", but in the local time of the monitoring location. It is retained for backwards compatibility, but will be removed in V1 of these APIs.} +\item{begin}{The datetime of the earliest observation in the time series. Together with \code{end}, this field represents the period of record of a time series. Note that some time series may have large gaps in their collection record. +You can query this field using date-times or intervals, adhering to RFC 3339, or using ISO 8601 duration objects. Intervals may be bounded or half-bounded (double-dots at start or end). +Examples: +\itemize{ +\item A date-time: "2018-02-12T23:20:50Z" +\item A bounded interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" +\item Half-bounded intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z" +\item Duration objects: "P1M" for data from the past month or "PT36H" for the last 36 hours +} + +Only features that have a \code{begin} that intersects the value of datetime are selected.} + +\item{end}{The datetime of the most recent observation in the time series. Data returned by this endpoint updates at most once per day, and potentially less frequently than that, and as such there may be more recent observations within a time series than the time series \code{end} value reflects. Together with \code{begin}, this field represents the period of record of a time series. It is additionally used to determine whether a time series is "active". +You can query this field using date-times or intervals, adhering to RFC 3339, or using ISO 8601 duration objects. Intervals may be bounded or half-bounded (double-dots at start or end). +Examples: +\itemize{ +\item A date-time: "2018-02-12T23:20:50Z" +\item A bounded interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" +\item Half-bounded intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z" +\item Duration objects: "P1M" for data from the past month or "PT36H" for the last 36 hours +} -\item{end}{This field contains the same information as "end_utc", but in the local time of the monitoring location. It is retained for backwards compatibility, but will be removed in V1 of these APIs.} +Only features that have a \code{end} that intersects the value of datetime are selected.} \item{\dots}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} From a7f4492060c1be6fa19777d64317727f61141c51 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Fri, 28 Aug 2026 13:58:37 -0500 Subject: [PATCH 02/11] Add news --- NEWS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/NEWS.md b/NEWS.md index f1ca1457..9074ab41 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,6 @@ dataRetrieval 2.7.26 =================== +* Switching to v1 of the Water Data APIs. * Added suite of read_ngwmn to access new National Groundwater Monitoring Network API. * Created get_monitoring_location_arguments to help users understand From f4cc62a01caf966d9012bf554229075b6326cde3 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Fri, 28 Aug 2026 14:19:30 -0500 Subject: [PATCH 03/11] Fix tests --- tests/testthat/tests_userFriendly_fxns.R | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index 23215ed9..b9a90db4 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -30,7 +30,11 @@ test_that("Unit value data returns correct types", { expect_equal( grep( x = attr(recent_uv, "request")[["url"]], - pattern = "https://api.waterdata.usgs.gov/ogcapi/v0/collections/continuous" + pattern = paste0( + "https://api.waterdata.usgs.gov/ogcapi/", + getOption("dataRetrieval.api_version"), + "/collections/continuous" + ) ), 1 ) @@ -38,7 +42,11 @@ test_that("Unit value data returns correct types", { expect_equal( grep( x = attr(spreadOver120, "request")[["url"]], - pattern = "https://api.waterdata.usgs.gov/ogcapi/v0/collections/continuous" + pattern = paste0( + "https://api.waterdata.usgs.gov/ogcapi/", + getOption("dataRetrieval.api_version"), + "/collections/continuous" + ) ), 1 ) From d8888bacbc694a3de60be3aacc7de6f52e52ab37 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Fri, 28 Aug 2026 14:26:37 -0500 Subject: [PATCH 04/11] Fix tests --- R/read_waterdata_ts_meta.R | 4 ++-- man/read_waterdata_ts_meta.Rd | 4 ++-- tests/testthat/tests_userFriendly_fxns.R | 3 ++- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/R/read_waterdata_ts_meta.R b/R/read_waterdata_ts_meta.R index 22b48789..d5c37a33 100644 --- a/R/read_waterdata_ts_meta.R +++ b/R/read_waterdata_ts_meta.R @@ -65,8 +65,8 @@ #' parameter_code = c("00060", "00010"), #' properties = c("monitoring_location_id", #' "parameter_code", -#' "begin_utc", -#' "end_utc", +#' "begin", +#' "end", #' "time_series_id"), #' skipGeometry = TRUE) #' diff --git a/man/read_waterdata_ts_meta.Rd b/man/read_waterdata_ts_meta.Rd index 23d52d18..63403401 100644 --- a/man/read_waterdata_ts_meta.Rd +++ b/man/read_waterdata_ts_meta.Rd @@ -207,8 +207,8 @@ meta_multi <- read_waterdata_ts_meta(monitoring_location_id = c("USGS-01491000" parameter_code = c("00060", "00010"), properties = c("monitoring_location_id", "parameter_code", - "begin_utc", - "end_utc", + "begin", + "end", "time_series_id"), skipGeometry = TRUE) diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index b9a90db4..cd05ed02 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -165,7 +165,8 @@ test_that("peak, rating curves, surface-water measurements", { Meas07227500.ex <- read_waterdata_field_measurements( monitoring_location_id = "USGS-07227500" ) - expect_is(Meas07227500.ex$time, "POSIXct") + + expect_is(Meas07227500.ex$time, "Date") expect_equal( nrow(read_waterdata_ts_meta( From 73306da6462fc06f90c6889ee970d2188f080966 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 8 Sep 2026 13:58:28 -0500 Subject: [PATCH 05/11] Update monitoring_location to convert dates if convertType --- R/read_waterdata_monitoring_location.R | 2 +- R/read_waterdata_ts_meta.R | 16 ++++++---------- man/read_waterdata_monitoring_location.Rd | 5 +++++ man/read_waterdata_ts_meta.Rd | 12 ++++-------- 4 files changed, 16 insertions(+), 19 deletions(-) diff --git a/R/read_waterdata_monitoring_location.R b/R/read_waterdata_monitoring_location.R index 898f891c..0ea5ff44 100644 --- a/R/read_waterdata_monitoring_location.R +++ b/R/read_waterdata_monitoring_location.R @@ -149,6 +149,7 @@ read_waterdata_monitoring_location <- function( bbox = NA, skipGeometry = NA, ..., + convertType = getOption("dataRetrieval.convertType"), limit = getOption("dataRetrieval.limit"), no_paging = getOption("dataRetrieval.no_paging"), chunk_size = getOption("dataRetrieval.site_chunk_size_meta"), @@ -159,7 +160,6 @@ read_waterdata_monitoring_location <- function( rlang::check_dots_empty() args <- mget(names(formals())) - args[["convertType"]] <- FALSE return_list <- get_ogc_data(args, output_id, service) diff --git a/R/read_waterdata_ts_meta.R b/R/read_waterdata_ts_meta.R index d5c37a33..0653a695 100644 --- a/R/read_waterdata_ts_meta.R +++ b/R/read_waterdata_ts_meta.R @@ -18,16 +18,6 @@ #' @param last_modified `r get_ogc_params("time-series-metadata")$last_modified` #' #' See also Details below for more information. -#' @param begin_utc Deprecated in v1. Use "begin" instead. -#' #' -#' See also Details below for more information. -#' @param end_utc Deprecated in v1. Use "end" instead. -#' -#' See also Details below for more information. -#' @param hydrologic_unit_code Deprecated in v1. Use `read_waterdata_combined_meta` for -#' similar functionality. -#' @param state_name Deprecated in v1. Use `read_waterdata_combined_meta` for -#' similar functionality. #' @param thresholds `r get_ogc_params("time-series-metadata")$thresholds` #' @param unit_of_measure `r get_ogc_params("time-series-metadata")$unit_of_measure` #' @param primary @@ -49,6 +39,12 @@ #' @param time_series_id `r get_ogc_params("time-series-metadata")$id` #' @param \dots Not used. Included to help differentiate official Water Data API arguments #' from more seldom used, optional dataRetrieval-specific arguments. +#' @param begin_utc Deprecated in v1. Use "begin" instead. +#' @param end_utc Deprecated in v1. Use "end" instead. +#' @param state_name Deprecated in v1. Use `read_waterdata_combined_meta` for +#' similar functionality. +#' @param hydrologic_unit_code Deprecated in v1. Use +#' `read_waterdata_combined_meta` for similar functionality. #' @inheritParams check_arguments_api #' @inheritParams check_arguments_non_api #' diff --git a/man/read_waterdata_monitoring_location.Rd b/man/read_waterdata_monitoring_location.Rd index ee2b32f7..573cbaf1 100644 --- a/man/read_waterdata_monitoring_location.Rd +++ b/man/read_waterdata_monitoring_location.Rd @@ -53,6 +53,7 @@ read_waterdata_monitoring_location( bbox = NA, skipGeometry = NA, ..., + convertType = getOption("dataRetrieval.convertType"), limit = getOption("dataRetrieval.limit"), no_paging = getOption("dataRetrieval.no_paging"), chunk_size = getOption("dataRetrieval.site_chunk_size_meta"), @@ -182,6 +183,10 @@ information. The default \code{NA} will not specify the argument in the request. \item{\dots}{Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.} +\item{convertType}{logical, defaults to TRUE. +If \code{TRUE}, the function will convert the data to dates, any qualifiers to string +vector and reorder the returned data frame.} + \item{limit}{numeric, The optional limit parameter is used to control the subset of the selected features that should be returned in each page. The maximum allowable limit is 50,000. It may be beneficial to set this number lower if your internet diff --git a/man/read_waterdata_ts_meta.Rd b/man/read_waterdata_ts_meta.Rd index 63403401..95300a17 100644 --- a/man/read_waterdata_ts_meta.Rd +++ b/man/read_waterdata_ts_meta.Rd @@ -70,16 +70,12 @@ Only features that have a \code{last_modified} that intersects the value of date See also Details below for more information.} -\item{begin_utc}{Deprecated in v1. Use "begin" instead. -#' -See also Details below for more information.} - -\item{end_utc}{Deprecated in v1. Use "end" instead. +\item{begin_utc}{Deprecated in v1. Use "begin" instead.} -See also Details below for more information.} +\item{end_utc}{Deprecated in v1. Use "end" instead.} -\item{hydrologic_unit_code}{Deprecated in v1. Use \code{read_waterdata_combined_meta} for -similar functionality.} +\item{hydrologic_unit_code}{Deprecated in v1. Use +\code{read_waterdata_combined_meta} for similar functionality.} \item{state_name}{Deprecated in v1. Use \code{read_waterdata_combined_meta} for similar functionality.} From 69c83ac5b422de2c830735d096caddbd7134cf7e Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 8 Sep 2026 15:26:36 -0500 Subject: [PATCH 06/11] the pcode_to_name doesn't work anymore --- NEWS.md | 1 + R/pcode_to_name.R | 65 +++++++++----------------------------------- man/pcode_to_name.Rd | 23 ++++++---------- 3 files changed, 22 insertions(+), 67 deletions(-) diff --git a/NEWS.md b/NEWS.md index 9074ab41..d7a4a6e1 100644 --- a/NEWS.md +++ b/NEWS.md @@ -8,6 +8,7 @@ what new optional arguments are available in many of the read_waterdata function * Added ability to use `...` in the Water Data functions for: daily, latest-continuous, field-measurements, latest-daily, latest-field-measurements, continuous, and peaks. The "..." argument can now accept any parameter that is output from the make_monitoring_location_arguments function. * Added "q" argument to read_waterdata_monitoring_location. Full-text search across the most relevant text fields for this collection (e.g. site name, identifier, number, state, county, and site type). * Added "skipGeometry" argument to read_waterdata_continuous. Previously geometry wasn't included with continuous data, but now is supported. +* Deprecated `pcode_to_name` since the service was removed. dataRetrieval 2.7.25 =================== diff --git a/R/pcode_to_name.R b/R/pcode_to_name.R index f99cb052..dab6cb6a 100644 --- a/R/pcode_to_name.R +++ b/R/pcode_to_name.R @@ -1,64 +1,25 @@ #' Parameter code to characteristic name #' -#' 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. +#' This function no longer works because the underlying service +#' has been removed. Similar functionality can be found with +#' `check_waterdata_sample_params`. #' #' @export #' @param parameterCd character that contains the code for a character vector -#' of 5-digit parameter codes. Default is "all" which will return a complete -#' list of parameter codes that have been mapped to a characteristic name. -#' @return a data frame with columns "parm_cd", "description", -#' "characteristicname", "measureunitcode", "resultsamplefraction", -#' "resulttemperaturebasis", "resultstatisticalbasis", "resulttimebasis", -#' "resultweightbasis", "resultparticlesizebasis", "last_rev_dt" +#' of 5-digit parameter codes. #' @examples #' pcodes <- c("00070", "00075", "00430", "52642") #' \donttest{ -#' -#' all <- pcode_to_name() -#' some <- pcode_to_name(pcodes) +#' all_new <- read_waterdata_parameter_codes(parameter_code = pcodes) +#' ref_list <- check_waterdata_sample_params("reference-list", +#' parm_cd = pcodes) +#' ref_list_sm <- ref_list[ref_list$parm_cd %in% pcodes, ] #' #' } pcode_to_name <- function(parameterCd = "all") { - parameterCd.orig <- parameterCd - parameterCd <- parameterCd[!is.na(parameterCd)] - - url_all <- "https://www.waterqualitydata.us/Codes/public_srsnames/?mimeType=json" - doc <- get_nldi_sources(url_all) - retval <- doc[["pcodes"]] - - if (all(tolower(parameterCd) != "all")) { - retval <- retval[retval$parm_cd %in% parameterCd, ] - } - - attr(retval, "url") <- url_all - - if (any(parameterCd != "all")) { - if (nrow(retval) != length(unique(parameterCd))) { - badPcode <- parameterCd[!(parameterCd %in% retval$parm_cd)] - warning( - "The following pCodes seem mistyped, and no information was returned: ", - paste(badPcode, collapse = ", ") - ) - } - } - - if (nrow(retval) != sum(is.na(parameterCd.orig))) { - na.params <- data.frame(matrix( - ncol = ncol(retval), - nrow = sum(is.na(parameterCd.orig)) - )) - names(na.params) <- names(retval) - retval <- rbind(retval, na.params) - } - - # order by parameterCd.orig - if (!isTRUE(parameterCd.orig == "all")) { - retval <- retval[match(parameterCd.orig, retval$parm_cd), ] - retval$parm_cd <- parameterCd.orig - } - - return(retval) + .Deprecated( + new = "check_waterdata_sample_params", + package = "dataRetrieval", + msg = "Convert to check_waterdata_sample_params('reference-list')." + ) } diff --git a/man/pcode_to_name.Rd b/man/pcode_to_name.Rd index dd3e1a4e..264c4f30 100644 --- a/man/pcode_to_name.Rd +++ b/man/pcode_to_name.Rd @@ -8,27 +8,20 @@ pcode_to_name(parameterCd = "all") } \arguments{ \item{parameterCd}{character that contains the code for a character vector -of 5-digit parameter codes. Default is "all" which will return a complete -list of parameter codes that have been mapped to a characteristic name.} -} -\value{ -a data frame with columns "parm_cd", "description", -"characteristicname", "measureunitcode", "resultsamplefraction", -"resulttemperaturebasis", "resultstatisticalbasis", "resulttimebasis", -"resultweightbasis", "resultparticlesizebasis", "last_rev_dt" +of 5-digit parameter codes.} } \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. +This function no longer works because the underlying service +has been removed. Similar functionality can be found with +\code{check_waterdata_sample_params}. } \examples{ pcodes <- c("00070", "00075", "00430", "52642") \donttest{ - -all <- pcode_to_name() -some <- pcode_to_name(pcodes) +all_new <- read_waterdata_parameter_codes(parameter_code = pcodes) +ref_list <- check_waterdata_sample_params("reference-list", + parm_cd = pcodes) +ref_list_sm <- ref_list[ref_list$parm_cd \%in\% pcodes, ] } } From 91dbdd89179fd9fb5af5adb06172c31cd776acb9 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 8 Sep 2026 15:33:47 -0500 Subject: [PATCH 07/11] ugg --- R/pcode_to_name.R | 3 +-- man/pcode_to_name.Rd | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/R/pcode_to_name.R b/R/pcode_to_name.R index dab6cb6a..e621106b 100644 --- a/R/pcode_to_name.R +++ b/R/pcode_to_name.R @@ -11,8 +11,7 @@ #' pcodes <- c("00070", "00075", "00430", "52642") #' \donttest{ #' all_new <- read_waterdata_parameter_codes(parameter_code = pcodes) -#' ref_list <- check_waterdata_sample_params("reference-list", -#' parm_cd = pcodes) +#' ref_list <- check_waterdata_sample_params("reference-list") #' ref_list_sm <- ref_list[ref_list$parm_cd %in% pcodes, ] #' #' } diff --git a/man/pcode_to_name.Rd b/man/pcode_to_name.Rd index 264c4f30..e61397db 100644 --- a/man/pcode_to_name.Rd +++ b/man/pcode_to_name.Rd @@ -19,8 +19,7 @@ has been removed. Similar functionality can be found with pcodes <- c("00070", "00075", "00430", "52642") \donttest{ all_new <- read_waterdata_parameter_codes(parameter_code = pcodes) -ref_list <- check_waterdata_sample_params("reference-list", - parm_cd = pcodes) +ref_list <- check_waterdata_sample_params("reference-list") ref_list_sm <- ref_list[ref_list$parm_cd \%in\% pcodes, ] } From b3145f549ed1711885594a5c140c14d17565dd82 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 8 Sep 2026 15:48:49 -0500 Subject: [PATCH 08/11] fix tests --- tests/testthat/tests_userFriendly_fxns.R | 26 ------------------------ 1 file changed, 26 deletions(-) diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index cd05ed02..f0f85b67 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -601,32 +601,6 @@ test_that("pCode Stuff", { expect_true(nrow(paramINFO) > 10000) }) -context("pCode Name Stuff") -test_that("pCode Stuff", { - testthat::skip_on_cran() - - paramINFO <- pcode_to_name(c("00060", "01075", "00931", NA)) - expect_equal(nrow(paramINFO), 4) - expect_equal(paramINFO$parm_cd, c("00060", "01075", "00931", NA)) - - # pcode 12345 isn't a valid code: - expect_warning(paramINFO <- pcode_to_name(c("12345"))) - expect_warning( - paramINFO <- pcode_to_name(c("00060", "01075", "12345", NA_character_)) - ) - expect_equal(nrow(paramINFO), 4) - expect_equal(paramINFO$parm_cd, c("00060", "01075", "12345", NA_character_)) - - expect_equal(paramINFO$description[3:4], c(NA_character_, NA_character_)) - - paramINFO <- pcode_to_name("all") - expect_true(nrow(paramINFO) > 19000) - expect_equal( - attr(paramINFO, "url"), - "https://www.waterqualitydata.us/Codes/public_srsnames/?mimeType=json" - ) -}) - context("Smart errors, warnings") test_that("bad_properties", { testthat::skip_on_cran() From 0252a4a2c75bda71c92f6323cdcbc18277d87700 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 9 Sep 2026 08:06:32 -0500 Subject: [PATCH 09/11] take out WQP tests until things are stabilized --- tests/testthat/tests_general.R | 234 ++++++++------------------------- 1 file changed, 54 insertions(+), 180 deletions(-) diff --git a/tests/testthat/tests_general.R b/tests/testthat/tests_general.R index ea8a2e03..f1ca15ae 100644 --- a/tests/testthat/tests_general.R +++ b/tests/testthat/tests_general.R @@ -243,18 +243,8 @@ test_that("read_waterdata_ts_meta", { test_that("General WQP retrievals working", { testthat::skip_on_cran() testthat::skip_on_ci() - # nameToUse <- "pH" - # pHData <- readWQPdata( - # siteid = "USGS-04024315", - # characteristicName = nameToUse, - # service = "ResultWQX3" - # ) - # expect_is(pHData$Activity_StartDateTime, "POSIXct") - # expect_type(pHData$USGSpcode, "character") - # expect_type(pHData$Result_Measure, "double") - # expect_type(pHData$SampleCollectionMethod_Identifier, "character") - # - # # testing lists: + + # testing lists: startDate <- as.Date("2022-01-01") secchi.names <- c( "Depth, Secchi disk depth", @@ -262,9 +252,6 @@ test_that("General WQP retrievals working", { "Water transparency, Secchi disc", "Depth, Secchi disk depth (choice list)" ) - # "Transparency, Secchi tube with disk", - # "Secchi Reading Condition (choice list)", - # "Depth, Secchi disk visible at bottom (Y/N) (choice list)") args_2 <- list( "startDateLo" = startDate, @@ -282,84 +269,8 @@ test_that("General WQP retrievals working", { statecode = "WI", characteristicName = secchi.names ) - - # wqp.summary_no_atts <- readWQPdata( - # siteid = "USGS-04024315", - # characteristicName = nameToUse, - # ignore_attributes = TRUE, - # service = "ResultWQX3" - # ) - # expect_true( - # !all( - # c("siteInfo", "variableInfo") %in% names(attributes(wqp.summary_no_atts)) - # ) - # ) - # - # rawPcode <- readWQPqw("USGS-01594440", "01075", "", "", legacy = FALSE) - # expect_true(all( - # c("url", "queryTime", "siteInfo") %in% - # names(attributes(rawPcode)) - # )) - # - # # This means wqp_check_status was called: - # expect_true("dataProviders" %in% names(attr(rawPcode, "headerInfo"))) - # - # rawPcode2 <- readWQPqw( - # "USGS-01594440", - # "01075", - # "", - # "", - # ignore_attributes = TRUE - # ) - # expect_true(all( - # !c("queryTime", "siteInfo") %in% - # names(attributes(rawPcode2)) - # )) - # - # # This means wqp_check_status wasn't called: - # expect_false("dataProviders" %in% names(attr(rawPcode2, "headerInfo"))) - # - # pHData <- readWQPdata( - # siteid = "USGS-04024315", - # characteristicName = "pH", - # service = "ResultWQX3" - # ) - # expect_true(all( - # c("url", "queryTime", "siteInfo", "headerInfo") %in% - # names(attributes(pHData)) - # )) - # - # # # This means wqp_check_status was called: - # expect_true("dataProviders" %in% names(attr(pHData, "headerInfo"))) - # - # pHData2 <- readWQPdata( - # siteid = "USGS-04024315", - # characteristicName = "pH", - # ignore_attributes = TRUE, - # service = "ResultWQX3" - # ) - # expect_true(all( - # !c("queryTime", "siteInfo") %in% - # names(attributes(pHData2)) - # )) - # - # # # This means wqp_check_status was called: - # expect_false("dataProviders" %in% names(attr(pHData2, "headerInfo"))) - # - # 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) - # - # expect_true("dataProviders" %in% names(count_info)) }) - test_that("zeroPad handles NAs", { toPad <- c(1, 5, 55, NA) padded <- zeroPad(toPad, 3) @@ -377,44 +288,6 @@ test_that("Dates with no days can be handled", { expect_true(nrow(empty_df) > 0) }) -context("whatWQPsamples") -test_that("whatWQPsamples working", { - testthat::skip_on_cran() - testthat::skip_on_ci() - # The warning is caused by a confirmed bug in WQP - siteInfo <- whatWQPsamples(siteid = "USGS-01594440") - expect_true(nrow(siteInfo) > 0) -}) - -context("whatWQPmetrics") -test_that("whatWQPmetrics working", { - testthat::skip_on_cran() - testthat::skip_on_ci() - type <- "Stream" - siteInfo <- whatWQPmetrics(countycode = "US:55:025", siteType = type) - expect_true(ncol(siteInfo) >= 21) -}) - -context("whatWQPdata") -test_that("whatWQPdata working", { - testthat::skip_on_cran() - testthat::skip_on_ci() - - site1 <- whatWQPdata(siteid = "USGS-01594440") - expect_is(site1, "data.frame") - expect_equal(1, nrow(site1)) - - type <- "Stream" - sites <- whatWQPdata(countycode = "US:55:025", siteType = type) - expect_gt(nrow(sites), 1) - - lakeSites <- whatWQPdata( - siteType = "Lake, Reservoir, Impoundment", - statecode = "US:55" - ) - expect_is(lakeSites$activityCount, "numeric") -}) - context("read_waterdata_ts_meta") test_that("read_waterdata_ts_meta working", { testthat::skip_on_cran() @@ -456,29 +329,29 @@ test_that("readWQPdots working", { expect_true("statecode" %in% names(formArgs$values)) expect_false("stateCd" %in% names(formArgs$values)) - bbox <- c(-86.97361, 34.48827, -86.61349, 34.65623) - what_bbox <- whatWQPdata(bBox = bbox) - expect_true(nrow(what_bbox) > 0) - x <- whatWQPsites(bBox = bbox) - expect_true(nrow(x) > 0) - df <- readWQPdata( - bBox = bbox, - characteristicName = "Total Coliform", - startDateLo = "2023-01-01", - startDateHi = "2023-12-31", - service = "Result", - dataProfile = "narrowResult" - ) - expect_true(nrow(df) > 0) - df_legacy <- readWQPdata( - bBox = bbox, - characteristicName = "Total Coliform", - startDateLo = "2023-01-01", - startDateHi = "2023-12-31", - service = "Result", - dataProfile = "narrowResult" - ) - expect_true(nrow(df_legacy) > 0) + # bbox <- c(-86.97361, 34.48827, -86.61349, 34.65623) + # what_bbox <- whatWQPdata(bBox = bbox) + # expect_true(nrow(what_bbox) > 0) + # x <- whatWQPsites(bBox = bbox) + # expect_true(nrow(x) > 0) + # df <- readWQPdata( + # bBox = bbox, + # characteristicName = "Total Coliform", + # startDateLo = "2023-01-01", + # startDateHi = "2023-12-31", + # service = "Result", + # dataProfile = "narrowResult" + # ) + # expect_true(nrow(df) > 0) + # df_legacy <- readWQPdata( + # bBox = bbox, + # characteristicName = "Total Coliform", + # startDateLo = "2023-01-01", + # startDateHi = "2023-12-31", + # service = "Result", + # dataProfile = "narrowResult" + # ) + # expect_true(nrow(df_legacy) > 0) }) @@ -522,32 +395,33 @@ test_that("internal functions", { }) -test_that("importWQP convertType", { - testthat::skip_on_cran() - - SC <- readWQPqw( - siteNumbers = "USGS-05288705", - parameterCd = "00300", - convertType = TRUE, - legacy = TRUE - ) - expect_in("ActivityStartDateTime", names(SC)) - - SC2 <- readWQPqw( - siteNumbers = "USGS-05288705", - parameterCd = "00300", - convertType = FALSE, - legacy = TRUE - ) - expect_true(!"ActivityStartDateTime" %in% names(SC2)) - - lakeSites_chars <- whatWQPdata( - siteType = "Lake, Reservoir, Impoundment", - statecode = "US:55", - convertType = FALSE - ) - expect_is(lakeSites_chars$lat, "character") -}) +# test_that("importWQP convertType", { +# testthat::skip_on_cran() +# testthat::skip_on_ci() +# +# SC <- readWQPqw( +# siteNumbers = "USGS-05288705", +# parameterCd = "00300", +# convertType = TRUE, +# legacy = TRUE +# ) +# expect_in("ActivityStartDateTime", names(SC)) +# +# SC2 <- readWQPqw( +# siteNumbers = "USGS-05288705", +# parameterCd = "00300", +# convertType = FALSE, +# legacy = TRUE +# ) +# expect_true(!"ActivityStartDateTime" %in% names(SC2)) +# +# lakeSites_chars <- whatWQPdata( +# siteType = "Lake, Reservoir, Impoundment", +# statecode = "US:55", +# convertType = FALSE +# ) +# expect_is(lakeSites_chars$lat, "character") +# }) test_that("format_dates", { start_end <- c("2021-01-01", "2022-01-01") @@ -615,13 +489,13 @@ test_that("format_dates", { "2021-01-01T17:15:00Z/.." ) - time = c("2014-05-01T00:00:00Z", "2014-05-01T12:00:00Z") + time <- c("2014-05-01T00:00:00Z", "2014-05-01T12:00:00Z") expect_equal( dataRetrieval:::format_api_dates(time), "2014-05-01T00:00:00Z/2014-05-01T12:00:00Z" ) - time = c("2014-05-01T00:00Z", "2014-05-01T12:00Z") + time <- c("2014-05-01T00:00Z", "2014-05-01T12:00Z") expect_equal( dataRetrieval:::format_api_dates(time), "2014-05-01T00:00:00Z/2014-05-01T12:00:00Z" From ff0284d027b358dff63e3c06f0121fb5c64113c7 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 9 Sep 2026 08:20:26 -0500 Subject: [PATCH 10/11] regenerate readme --- README.md | 199 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 129 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index 9ea1d996..76dd95ad 100644 --- a/README.md +++ b/README.md @@ -1,69 +1,87 @@ ---- -title: "README" -output: - md_document: - variant: gfm -editor_options: - chunk_output_type: console ---- - - - - # dataRetrieval -[![CRAN version](http://www.r-pkg.org/badges/version/dataRetrieval)](https://cran.r-project.org/package=dataRetrieval) +[![CRAN +version](http://www.r-pkg.org/badges/version/dataRetrieval)](https://cran.r-project.org/package=dataRetrieval) [![](http://cranlogs.r-pkg.org/badges/dataRetrieval)](https://cran.r-project.org/package=dataRetrieval) [![](http://cranlogs.r-pkg.org/badges/grand-total/dataRetrieval)](https://cran.r-project.org/package=dataRetrieval) -The `dataRetrieval` package was created to simplify the process of loading hydrologic data into the R environment. It is designed to retrieve the major data types of U.S. Geological Survey (USGS) hydrology data that are available on the Web, as well as data from the Water Quality Portal (WQP), which currently houses water quality data from the Environmental Protection Agency (EPA), U.S. Department of Agriculture (USDA), and USGS. +The `dataRetrieval` package was created to simplify the process of +loading hydrologic data into the R environment. It is designed to +retrieve the major data types of U.S. Geological Survey (USGS) hydrology +data that are available on the Web, as well as data from the Water +Quality Portal (WQP), which currently houses water quality data from the +Environmental Protection Agency (EPA), U.S. Department of Agriculture +(USDA), and USGS. # Introduction -:warning: NWIS web services (readNWIS functions) will be replaced over time by USGS Water Data APIs (read_waterdata_). Read more about it here: +:warning: NWIS web services (readNWIS functions) will be replaced over +time by USGS Water Data APIs (read_waterdata\_). Read more about it +here: -:warning: USGS discrete water-quality data availability and format are changing. To view the status of changes in data availability and code functionality, visit: +:warning: USGS discrete water-quality data availability and format are +changing. To view the status of changes in data availability and code +functionality, visit: + -If you have additional questions about these changes, email CompTools@usgs.gov. +If you have additional questions about these changes, email +. # Feedback requested -We at USGS Water Data for the Nation want your feedback! Tell us how we're doing by taking our quick survey: +We at USGS Water Data for the Nation want your feedback! Tell us how +we’re doing by taking our quick survey: + # What would you like to do? -1. Get instantaneous USGS data (for example, discharge sensor data). Start here: `?read_waterdata_continuous`. If you only need the latest value, you can use the function: `?read_waterdata_latest_continuous`. +1. Get instantaneous USGS data (for example, discharge sensor data). + Start here: `?read_waterdata_continuous`. If you only need the + latest value, you can use the function: + `?read_waterdata_latest_continuous`. -2. Get daily USGS data (for example, mean daily discharge). Start here: `?read_waterdata_daily`. If you only need the latest value, you can use the function: `?read_waterdata_latest_daily`. +2. Get daily USGS data (for example, mean daily discharge). Start here: + `?read_waterdata_daily`. If you only need the latest value, you can + use the function: `?read_waterdata_latest_daily`. -3. Get discrete USGS groundwater data. Start here: `?read_waterdata_field_measurements` +3. Get discrete USGS groundwater data. Start here: + `?read_waterdata_field_measurements` -4. Get discrete water quality data from a cooperative service that integrates publicly available water-quality data from the USGS, EPA, and over 400 state, federal, tribal, and local agencies. Start here: `?readWQPdata` +4. Get discrete water quality data from a cooperative service that + integrates publicly available water-quality data from the USGS, EPA, + and over 400 state, federal, tribal, and local agencies. Start here: + `?readWQPdata` -5. Get USGS discrete water quality data. Start here: `?read_waterdata_samples` +5. Get USGS discrete water quality data. Start here: + `?read_waterdata_samples` -6. Get metadata about USGS time series data, including instantaneous and daily data. Start here: `?read_waterdata_ts_meta` +6. Get metadata about USGS time series data, including instantaneous + and daily data. Start here: `?read_waterdata_ts_meta` -7. Find Hydro Network-Linked Data Index (NLDI) data. Start here: `?findNLDI` +7. Find Hydro Network-Linked Data Index (NLDI) data. Start here: + `?findNLDI` -9. Get daily data statistics. Start here: `?read_waterdata_stats_por` +8. Get daily data statistics. Start here: `?read_waterdata_stats_por` -10. Add a USGS WaterData API token to your R environment. See: +9. Add a USGS WaterData API token to your R environment. See: + -11. Get the latest status on NWIS, WQP, and other data access updates. See: +10. Get the latest status on NWIS, WQP, and other data access updates. + See: For additional tutorials, see: -[Basic Tutorial](https://doi-usgs.github.io/dataRetrieval/articles/tutorial.html) - -[dataRetrieval Introduction Slideshow](https://doi-usgs.github.io/dataRetrieval/tutorials/basic_slides_deck.html#/title-slide) +[Basic +Tutorial](https://doi-usgs.github.io/dataRetrieval/articles/tutorial.html) +[dataRetrieval Introduction +Slideshow](https://doi-usgs.github.io/dataRetrieval/tutorials/basic_slides_deck.html#/title-slide) # Installation of dataRetrieval -To install the `dataRetrieval` package, you must be using R 3.0 or greater and run the following command: - +To install the `dataRetrieval` package, you must be using R 3.0 or +greater and run the following command: ``` r install.packages("dataRetrieval") @@ -71,33 +89,53 @@ install.packages("dataRetrieval") # New USGS data access -The USGS is planning to modernize all web services in the near future. For each of these updates, `dataRetrieval` will create a new function to access the new services. +The USGS is planning to modernize all web services in the near future. +For each of these updates, `dataRetrieval` will create a new function to +access the new services. ## API Token -You can register an API key for use with USGS water data APIs. There are now limits on how many queries can be requested per IP address per hour. If you find yourself running into limits, you can request an API token here: +You can register an API key for use with USGS water data APIs. There are +now limits on how many queries can be requested per IP address per hour. +If you find yourself running into limits, you can request an API token +here: Then save your token in your .Renviron file like this: -``` -API_USGS_PAT = "my_super_secret_token" -``` + API_USGS_PAT = "my_super_secret_token" -You can use `usethis::edit_r_environ()` to edit find and open your .Renviron file. You will need to restart R for that variable to be recognized. +You can use `usethis::edit_r_environ()` to edit find and open your +.Renviron file. You will need to restart R for that variable to be +recognized. ## New Features ### Style -New functions will use a "snake case", such as "read_waterdata_samples". Older functions use camel case, such as "readNWISdv". The difference is the underscore between words. This should be a handy way to tell the difference between newer modern data access, and the older traditional functions. +New functions will use a “snake case”, such as “read_waterdata_samples”. +Older functions use camel case, such as “readNWISdv”. The difference is +the underscore between words. This should be a handy way to tell the +difference between newer modern data access, and the older traditional +functions. ### Structure -Historically, we allowed users to customize their queries via the `...` argument structure. With `...`, users needed to know the exact names of query parameters before using the function. Now, the new functions will include **ALL** possible arguments that the web service APIs support. This will allow users to use tab-autocompletes (available in RStudio and other IDEs). **Users will need to understand that it is not advisable to specify all of these parameters. The systems can get bogged down with redundant query parameters.** We expect this will be easier for users, but it might take some time to smooth out the documentation and test usability. There may be additional consequences, such as users won't be able to build up argument lists to pass into the function. +Historically, we allowed users to customize their queries via the `...` +argument structure. With `...`, users needed to know the exact names of +query parameters before using the function. Now, the new functions will +include **ALL** possible arguments that the web service APIs support. +This will allow users to use tab-autocompletes (available in RStudio and +other IDEs). **Users will need to understand that it is not advisable to +specify all of these parameters. The systems can get bogged down with +redundant query parameters.** We expect this will be easier for users, +but it might take some time to smooth out the documentation and test +usability. There may be additional consequences, such as users won’t be +able to build up argument lists to pass into the function. ### Dependencies -As we develop functions for the modern USGS Water Data APIs, we'll continue to explore updating package dependencies. +As we develop functions for the modern USGS Water Data APIs, we’ll +continue to explore updating package dependencies. ### Developmental workflow @@ -107,8 +145,13 @@ CRAN-stable documentation will be available on the GitHub pages: In-development documentation will be available on the USGS GitLab pages: -Development of `dataRetrieval` will happen on a git branch called "develop". The "develop" branch will only move to the "main" branch when we submit to CRAN, unless there are bug fixes that pertain to the CRAN release. The "develop" branch WILL change frequently, and there are no promises of future behavior. Users must accept that they are using those functions at their own risk. If you willing to accept this risk, the installation instructions are: - +Development of `dataRetrieval` will happen on a git branch called +“develop”. The “develop” branch will only move to the “main” branch when +we submit to CRAN, unless there are bug fixes that pertain to the CRAN +release. The “develop” branch WILL change frequently, and there are no +promises of future behavior. Users must accept that they are using those +functions at their own risk. If you willing to accept this risk, the +installation instructions are: ``` r library(remotes) @@ -116,23 +159,23 @@ library(remotes) install_github("DOI-USGS/dataRetrieval", ref = "develop") ``` - # Reporting bugs Please consider reporting bugs and asking questions on the Issues page: -[https://github.com/DOI-USGS/dataRetrieval/issues](https://github.com/DOI-USGS/dataRetrieval/issues) + # Citations ## Citing the dataRetrieval package - ``` r citation(package = "dataRetrieval") #> To cite dataRetrieval in publications, please use: #> -#> De Cicco, L.A., Hirsch, R.M., Lorenz, D., Watkins, W.D., Johnson, M., Blodgett, D.L., Hinman, E.D., Zemmels, J., 2026, dataRetrieval: R packages -#> for discovering and retrieving water data available from Federal hydrologic web services, v.2.7.25, doi:10.5066/P9X4L3GE +#> De Cicco, L.A., Hirsch, R.M., Lorenz, D., Watkins, W.D., Johnson, M., +#> Blodgett, D.L., Hinman, E.D., Zemmels, J., 2026, dataRetrieval: R +#> packages for discovering and retrieving water data available from +#> Federal hydrologic web services, v.2.7.25, doi:10.5066/P9X4L3GE #> #> A BibTeX entry for LaTeX users is #> @@ -150,12 +193,13 @@ citation(package = "dataRetrieval") ## Citing NWIS data -U.S. Geological Survey, 2023, National Water Information System data available on the World Wide Web (USGS Water Data for the Nation), accessed [April 26, 2023], at http://waterdata.usgs.gov/nwis/. http://dx.doi.org/10.5066/F7P55KJN +U.S. Geological Survey, 2023, National Water Information System data +available on the World Wide Web (USGS Water Data for the Nation), +accessed \[April 26, 2023\], at . + This can be done using the `create_NWIS_bib` function: - - ``` r dv <- read_waterdata_daily( @@ -166,14 +210,16 @@ dv <- read_waterdata_daily( NWIScitation <- create_NWIS_bib(dv) NWIScitation -#> U.S. Geological Survey (2026). _USGS Water Data for the Nation: U.S. Geological Survey National Water Information System database_. -#> doi:10.5066/F7P55KJN , Accessed Sep 01, 2026. +#> U.S. Geological Survey (2026). _USGS Water Data for the Nation: U.S. +#> Geological Survey National Water Information System database_. +#> doi:10.5066/F7P55KJN . Accessed Sep +#> 09, 2026. print(NWIScitation, style = "Bibtex") #> @Manual{, #> title = {USGS Water Data for the Nation: U.S. Geological Survey National Water Information System database}, #> author = {{U.S. Geological Survey}}, #> doi = {10.5066/F7P55KJN}, -#> note = {Accessed Sep 01, 2026}, +#> note = {Accessed Sep 09, 2026}, #> year = {2026}, #> } ``` @@ -182,24 +228,27 @@ print(NWIScitation, style = "Bibtex") Citations for specific datasets should use this format: -National Water Quality Monitoring Council, YYYY, Water Quality Portal, accessed mm, dd, yyyy, hyperlink_for_query, https://doi.org/10.5066/P9QRKUVJ. +National Water Quality Monitoring Council, YYYY, Water Quality Portal, +accessed mm, dd, yyyy, hyperlink_for_query, +. This can be done using the `create_WQP_bib` function: - ``` r SC <- readWQPqw(siteNumbers = "USGS-05288705", parameterCd = "00300") WQPcitation <- create_WQP_bib(SC) WQPcitation -#> National Water Quality Monitoring Council (2026). _Water Quality Portal_. doi:10.5066/P9QRKUVJ , Accessed Sep -#> 01, 2026, . +#> National Water Quality Monitoring Council (2026). _Water Quality +#> Portal_. doi:10.5066/P9QRKUVJ . +#> Accessed Sep 09, 2026, +#> . print(WQPcitation, style = "Bibtex") #> @Manual{, #> title = {Water Quality Portal}, #> author = {{National Water Quality Monitoring Council}}, #> doi = {10.5066/P9QRKUVJ}, -#> note = {Accessed Sep 01, 2026}, +#> note = {Accessed Sep 09, 2026}, #> year = {2026}, #> url = {https://www.waterqualitydata.us/data/Result/search?siteid=USGS-05288705&count=no&pCode=00300&mimeType=csv}, #> } @@ -209,16 +258,26 @@ print(WQPcitation, style = "Bibtex") General Water Quality Portal citations should use the following: -Water Quality Portal. Washington (DC): National Water Quality Monitoring Council, United States Geological Survey (USGS), Environmental Protection Agency (EPA); 2021. https://doi.org/10.5066/P9QRKUVJ. +Water Quality Portal. Washington (DC): National Water Quality Monitoring +Council, United States Geological Survey (USGS), Environmental +Protection Agency (EPA); 2021. . # Package Support -The Water Mission Area of the USGS supports the development and maintenance of `dataRetrieval`, and most likely further into the future. Resources are available primarily for maintenance and responding to user questions. Priorities on the development of new features are determined by the `dataRetrieval` development team. - - -Disclaimer -========== - -This software is preliminary or provisional and is subject to revision. It is being provided to meet the need for timely best science. The software has not received final approval by the U.S. Geological Survey (USGS). No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. The software is provided on the condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from the authorized or unauthorized use of the software. - - +The Water Mission Area of the USGS supports the development and +maintenance of `dataRetrieval`, and most likely further into the future. +Resources are available primarily for maintenance and responding to user +questions. Priorities on the development of new features are determined +by the `dataRetrieval` development team. + +# Disclaimer + +This software is preliminary or provisional and is subject to revision. +It is being provided to meet the need for timely best science. The +software has not received final approval by the U.S. Geological Survey +(USGS). No warranty, expressed or implied, is made by the USGS or the +U.S. Government as to the functionality of the software and related +material nor shall the fact of release constitute any such warranty. The +software is provided on the condition that neither the USGS nor the U.S. +Government shall be held liable for any damages resulting from the +authorized or unauthorized use of the software. From 25dd2c750cacafe25215677008cc9dff64bbc677 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 9 Sep 2026 08:49:19 -0500 Subject: [PATCH 11/11] Fix any sketchy URLs --- R/citations.R | 5 +++ R/dataRetrieval-package.R | 7 ++-- R/readWQPdata.R | 3 +- R/whatWQPdata.R | 10 ++---- R/whatWQPsites.R | 20 ++++-------- README.Rmd | 17 +--------- README.md | 33 ++----------------- man/pCodeToName.Rd | 3 +- man/readWQPdata.Rd | 3 +- man/readWQPsummary.Rd | 9 ++--- man/whatWQPdata.Rd | 8 ++--- man/wqpSpecials.Rd | 9 ++--- vignettes/dataRetrieval.Rmd | 65 +++---------------------------------- 13 files changed, 36 insertions(+), 156 deletions(-) diff --git a/R/citations.R b/R/citations.R index cfbd16b2..fd43227e 100644 --- a/R/citations.R +++ b/R/citations.R @@ -23,6 +23,11 @@ #' print(nwis_citation, style = "citation") #' } create_NWIS_bib <- function(x) { + .Deprecated( + package = "dataRetrieval", + msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata functions." + ) + textVersion <- paste0( "U.S. Geological Survey, ", format(attr(x, "queryTime"), "%Y"), diff --git a/R/dataRetrieval-package.R b/R/dataRetrieval-package.R index 0f0d1da4..9570542d 100644 --- a/R/dataRetrieval-package.R +++ b/R/dataRetrieval-package.R @@ -69,9 +69,6 @@ NULL #' Data to convert USGS parameter code to characteristic names #' -#' Data pulled from Water Quality Portal on December 20, 2021. The data was pulled from -#' . -#' #' @name pCodeToName #' @return pCodeToName data frame with information about USGS parameters and how they #' relate to characteristic names (useful for WQP requests). @@ -208,14 +205,14 @@ NULL # "field-measurements", "latest-daily", # "continuous", "field-measurements-metadata", # "combined-metadata", "channel-measurements", "peaks") -# +# # property_list <- list() # for(service in services){ # property_list[[service]] <- dataRetrieval:::get_properties_for_docs(service) # } # # num_cols <- c("value", "contributing_drainage_area", "drainage_area", -# #"altitude_accuracy", +# #"altitude_accuracy", # "well_construction_depth", # "hole_construction_depth", "channel_flow", "channel_width", # "channel_area", "channel_velocity", "channel_location_distance") diff --git a/R/readWQPdata.R b/R/readWQPdata.R index d9ff92a9..d8c5ad0d 100644 --- a/R/readWQPdata.R +++ b/R/readWQPdata.R @@ -40,8 +40,7 @@ #' Sampling Activity \tab ActivityWQX3 \tab /wqx3/Activity/search \cr #' } #' -#' @param \dots see for a complete list of options. -#' A list of arguments can also be supplied. For more information see the above +#' @param \dots A list of arguments can also be supplied. For more information see the above #' description for this help file. One way to figure out how to construct a WQP query is to go to the "Advanced" #' form in the Water Quality Portal. Use the form to discover what parameters are available. Once the query is #' set in the form, scroll down to the "Query URL". You will see the parameters diff --git a/R/whatWQPdata.R b/R/whatWQPdata.R index 98e1e998..8adb85e0 100644 --- a/R/whatWQPdata.R +++ b/R/whatWQPdata.R @@ -33,7 +33,7 @@ whatWQPsamples <- function(..., convertType = TRUE, legacy = TRUE) { } else { baseURL <- httr2::request(pkg.env[["ActivityWQX3"]]) } - POST = FALSE + POST <- FALSE if (!legacy) { baseURL <- httr2::req_url_query(baseURL, !!!values, .multi = "explode") } else { @@ -147,8 +147,6 @@ whatWQPmetrics <- function(..., convertType = TRUE) { #' #' Returns a list of sites from the Water Quality Portal web service. This function gets #' the data from: . -#' Arguments to the function should be based on -#' . #' 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 @@ -158,11 +156,9 @@ whatWQPmetrics <- function(..., convertType = TRUE) { #' not learn what specific nutrients are available at that site. For that #' kind of data discovery see `readWQPsummary`. #' -#' @param \dots see for -#' a complete list of options. A list of arguments can also be supplied. +#' @param \dots A list of named arguments. #' One way to figure out how to construct a WQP query is to go to the "Advanced" -#' form in the Water Quality Portal: -#' +#' form in the Water Quality Portal. #' Use the form to discover what parameters are available. Once the query is #' set in the form, scroll down to the "Query URL". You will see the parameters #' after "https://www.waterqualitydata.us/#". For example, if you chose "Nutrient" diff --git a/R/whatWQPsites.R b/R/whatWQPsites.R index 08a2fde4..ef84b21f 100644 --- a/R/whatWQPsites.R +++ b/R/whatWQPsites.R @@ -2,17 +2,14 @@ #' #' Returns a list of sites from the Water Quality Portal web service. This function #' gets the data from: . -#' Arguments to the function should be based on -#' . The return from +#' 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. #' -#' @param \dots see -#' for a complete list of options. A list of arguments can also be supplied. +#' @param \dots A list of named arguments. #' One way to figure out how to construct a WQP query is to go to the "Advanced" -#' form in the Water Quality Portal: -#' +#' form in the Water Quality Portal. #' Use the form to discover what parameters are available. Once the query is #' set in the form, scroll down to the "Query URL". You will see the parameters #' after "https://www.waterqualitydata.us/#". For example, if you chose "Nutrient" @@ -53,7 +50,7 @@ whatWQPsites <- function(..., legacy = TRUE, convertType = TRUE) { if (any(c("tz", "service") %in% names(values))) { values <- values[!(names(values) %in% c("tz", "service"))] } - POST = FALSE + POST <- FALSE if (legacy) { baseURL <- httr2::request(pkg.env[["Station"]]) @@ -94,16 +91,13 @@ whatWQPsites <- function(..., legacy = TRUE, convertType = TRUE) { #' #' Returns a list of sites with year-by-year information on what data is available. #' The function gets the data from: . -#' Arguments to the function should be based on -#' . #' The information returned from this function describes the #' available data at the WQP sites, and some metadata on the sites themselves. #' -#' @param \dots see -#' for a complete list of options. A list of arguments can also be supplied. +#' @param \dots Named arguments. +#' A list of arguments can also be supplied. #' One way to figure out how to construct a WQP query is to go to the "Advanced" -#' form in the Water Quality Portal: -#' +#' form in the Water Quality Portal. #' Use the form to discover what parameters are available. Once the query is #' set in the form, scroll down to the "Query URL". You will see the parameters #' after "https://www.waterqualitydata.us/#". For example, if you chose "Nutrient" diff --git a/README.Rmd b/README.Rmd index b4632d54..eb1b6d70 100644 --- a/README.Rmd +++ b/README.Rmd @@ -141,23 +141,8 @@ citation(package = "dataRetrieval") ## Citing NWIS data -U.S. Geological Survey, 2023, National Water Information System data available on the World Wide Web (USGS Water Data for the Nation), accessed [April 26, 2023], at http://waterdata.usgs.gov/nwis/. http://dx.doi.org/10.5066/F7P55KJN +U.S. Geological Survey, 2026, USGS Water Data for the Nation: U.S. Geological Survey National Water Information System database, accessed [April 26, 2026], at http://dx.doi.org/10.5066/F7P55KJN -This can be done using the `create_NWIS_bib` function: - - -```{r} - -dv <- read_waterdata_daily( - monitoring_location_id = "USGS-09010500", - parameter_code = "00060" -) - -NWIScitation <- create_NWIS_bib(dv) - -NWIScitation -print(NWIScitation, style = "Bibtex") -``` ## Citing WQP data diff --git a/README.md b/README.md index 76dd95ad..c5b22000 100644 --- a/README.md +++ b/README.md @@ -193,36 +193,9 @@ citation(package = "dataRetrieval") ## Citing NWIS data -U.S. Geological Survey, 2023, National Water Information System data -available on the World Wide Web (USGS Water Data for the Nation), -accessed \[April 26, 2023\], at . - - -This can be done using the `create_NWIS_bib` function: - -``` r - -dv <- read_waterdata_daily( - monitoring_location_id = "USGS-09010500", - parameter_code = "00060" -) - -NWIScitation <- create_NWIS_bib(dv) - -NWIScitation -#> U.S. Geological Survey (2026). _USGS Water Data for the Nation: U.S. -#> Geological Survey National Water Information System database_. -#> doi:10.5066/F7P55KJN . Accessed Sep -#> 09, 2026. -print(NWIScitation, style = "Bibtex") -#> @Manual{, -#> title = {USGS Water Data for the Nation: U.S. Geological Survey National Water Information System database}, -#> author = {{U.S. Geological Survey}}, -#> doi = {10.5066/F7P55KJN}, -#> note = {Accessed Sep 09, 2026}, -#> year = {2026}, -#> } -``` +U.S. Geological Survey, 2026, USGS Water Data for the Nation: U.S. +Geological Survey National Water Information System database, accessed +\[April 26, 2026\], at ## Citing WQP data diff --git a/man/pCodeToName.Rd b/man/pCodeToName.Rd index f9d8f498..5608bd10 100644 --- a/man/pCodeToName.Rd +++ b/man/pCodeToName.Rd @@ -24,8 +24,7 @@ last_rev_dt \tab character \tab Latest revision of information\cr } } \description{ -Data pulled from Water Quality Portal on December 20, 2021. The data was pulled from -\url{https://www.waterqualitydata.us/Codes/public_srsnames/?mimeType=csv}. +Data to convert USGS parameter code to characteristic names } \examples{ head(pCodeToName[, 1:2]) diff --git a/man/readWQPdata.Rd b/man/readWQPdata.Rd index a2a915b4..72ad7122 100644 --- a/man/readWQPdata.Rd +++ b/man/readWQPdata.Rd @@ -14,8 +14,7 @@ readWQPdata( ) } \arguments{ -\item{\dots}{see \url{https://www.waterqualitydata.us/webservices_documentation} for a complete list of options. -A list of arguments can also be supplied. For more information see the above +\item{\dots}{A list of arguments can also be supplied. For more information see the above description for this help file. One way to figure out how to construct a WQP query is to go to the "Advanced" form in the Water Quality Portal. Use the form to discover what parameters are available. Once the query is set in the form, scroll down to the "Query URL". You will see the parameters diff --git a/man/readWQPsummary.Rd b/man/readWQPsummary.Rd index a939331e..9d1f3733 100644 --- a/man/readWQPsummary.Rd +++ b/man/readWQPsummary.Rd @@ -7,11 +7,10 @@ readWQPsummary(...) } \arguments{ -\item{\dots}{see \url{https://www.waterqualitydata.us/webservices_documentation} -for a complete list of options. A list of arguments can also be supplied. +\item{\dots}{Named arguments. +A list of arguments can also be supplied. One way to figure out how to construct a WQP query is to go to the "Advanced" -form in the Water Quality Portal: -\url{https://www.waterqualitydata.us/#mimeType=csv&providers=NWIS&providers=STORET} +form in the Water Quality Portal. Use the form to discover what parameters are available. Once the query is set in the form, scroll down to the "Query URL". You will see the parameters after "https://www.waterqualitydata.us/#". For example, if you chose "Nutrient" @@ -27,8 +26,6 @@ about the data available for the query parameters. \description{ Returns a list of sites with year-by-year information on what data is available. The function gets the data from: \url{https://www.waterqualitydata.us}. -Arguments to the function should be based on -\url{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. } diff --git a/man/whatWQPdata.Rd b/man/whatWQPdata.Rd index b16183d0..d12fa24a 100644 --- a/man/whatWQPdata.Rd +++ b/man/whatWQPdata.Rd @@ -7,11 +7,9 @@ whatWQPdata(..., convertType = TRUE) } \arguments{ -\item{\dots}{see \url{https://www.waterqualitydata.us/webservices_documentation} for -a complete list of options. A list of arguments can also be supplied. +\item{\dots}{A list of named arguments. One way to figure out how to construct a WQP query is to go to the "Advanced" -form in the Water Quality Portal: -\url{https://www.waterqualitydata.us/#mimeType=csv&providers=NWIS&providers=STORET} +form in the Water Quality Portal. Use the form to discover what parameters are available. Once the query is set in the form, scroll down to the "Query URL". You will see the parameters after "https://www.waterqualitydata.us/#". For example, if you chose "Nutrient" @@ -32,8 +30,6 @@ query parameters for the Water Quality Portal. \description{ Returns a list of sites from the Water Quality Portal web service. This function gets the data from: \url{https://www.waterqualitydata.us}. -Arguments to the function should be based on -\url{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 diff --git a/man/wqpSpecials.Rd b/man/wqpSpecials.Rd index a0d0fd84..37f2b9f6 100644 --- a/man/wqpSpecials.Rd +++ b/man/wqpSpecials.Rd @@ -13,11 +13,9 @@ whatWQPmetrics(..., convertType = TRUE) whatWQPsites(..., legacy = TRUE, convertType = TRUE) } \arguments{ -\item{\dots}{see \url{https://www.waterqualitydata.us/webservices_documentation} -for a complete list of options. A list of arguments can also be supplied. +\item{\dots}{A list of named arguments. One way to figure out how to construct a WQP query is to go to the "Advanced" -form in the Water Quality Portal: -\url{https://www.waterqualitydata.us/#mimeType=csv&providers=NWIS&providers=STORET} +form in the Water Quality Portal. Use the form to discover what parameters are available. Once the query is set in the form, scroll down to the "Query URL". You will see the parameters after "https://www.waterqualitydata.us/#". For example, if you chose "Nutrient" @@ -42,8 +40,7 @@ data frame that includes information on site metadata. \description{ Returns a list of sites from the Water Quality Portal web service. This function gets the data from: \url{https://www.waterqualitydata.us}. -Arguments to the function should be based on -\url{https://www.waterqualitydata.us/webservices_documentation}. The return from +The return from this function returns the basic metadata on WQP sites. It is generally faster than the \code{\link[=whatWQPdata]{whatWQPdata()}} function, but does not return information on what data was collected at the site. diff --git a/vignettes/dataRetrieval.Rmd b/vignettes/dataRetrieval.Rmd index 4614fe95..83e1f3f9 100644 --- a/vignettes/dataRetrieval.Rmd +++ b/vignettes/dataRetrieval.Rmd @@ -451,7 +451,7 @@ specificCond <- readWQPqw( ## WQP -Just as with NWIS, the Water Quality Portal (WQP) offers a variety of ways to search for sites and request data. The possible Web service arguments for WQP site searches is found [here](https://www.waterqualitydata.us/webservices_documentation). +Just as with NWIS, the Water Quality Portal (WQP) offers a variety of ways to search for sites and request data. ### Sites: whatWQPsites @@ -546,68 +546,11 @@ vignette(topic = "qwdata_changes", package = "dataRetrieval") citation(package = "dataRetrieval") ``` -## Citing NWIS data +## Citing Water Data API data -The requested format is: +Example: -U.S. Geological Survey, 2023, National Water Information System data available on the World Wide Web (USGS Water Data for the Nation), accessed [April 26, 2023], at https://dx.doi.org/10.5066/F7P55KJN - -This can be created from the attributes of the data using the `create_NWIS_bib` function: - - -```{r nwisCite, eval=FALSE} - -dv <- read_waterdata_daily(monitoring_location_id = "USGS-04085427", - parameter_code = "00060", - time = c("2012-01-01", "2012-06-30")) - -NWIScitation <- create_NWIS_bib(dv) -NWIScitation -``` - -``` -U.S. Geological Survey (2026). _USGS Water Data for the Nation: U.S. Geological Survey -National Water Information System database_. doi:10.5066/F7P55KJN -, Accessed Mar 09, 2026. -``` -Alternative output is available: - -```{r show1, eval=FALSE} -print(NWIScitation, style = "Bibtex") -``` - -``` -@Manual{, - title = {USGS Water Data for the Nation: U.S. Geological Survey National Water Information System database}, - author = {{U.S. Geological Survey}}, - doi = {10.5066/F7P55KJN}, - note = {Accessed Mar 09, 2026}, - year = {2026}, -} -``` - -```{r show2, eval=FALSE} -print(NWIScitation, style = "citation") -``` - -``` -U.S. Geological Survey, 2024, National Water Information System -data available on the World Wide Web (USGS Water Data for the -Nation), accessed Feb 09, 2024, at -https://waterservices.usgs.gov/nwis/dv/?site=09010500&format=waterml,1.1&ParameterCd=00060&StatCd=00003&startDT=1851-01-01, -https://dx.doi.org/10.5066/F7P55KJN - -A BibTeX entry for LaTeX users is - - @Manual{, - title = {National Water Information System data available on the World Wide Web (USGS Water Data for the Nation)}, - author = {{U.S. Geological Survey}}, - doi = {10.5066/F7P55KJN}, - note = {Accessed Feb 09, 2024}, - year = {2024}, - url = {https://waterservices.usgs.gov/nwis/dv/?site=09010500&format=waterml,1.1&ParameterCd=00060&StatCd=00003&startDT=1851-01-01}, - } -``` +U.S. Geological Survey, 2026, USGS Water Data for the Nation: U.S. Geological Survey National Water Information System database, accessed [April 26, 2026], at http://dx.doi.org/10.5066/F7P55KJN