read_waterdata: Generalized USGS Water Data API retrieval function

In dataRetrieval: Retrieval Functions for USGS and EPA Hydrology and Water Quality Data

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 = getOption("dataRetrieval.convertType"),
  limit = getOption("dataRetrieval.limit"),
  attach_request = getOption("dataRetrieval.attach_request")
)

Arguments

service	character, can be any existing collection.
CQL	A string in a Common Query Language format.
...	Additional arguments to send to the request.
convertType	logical, defaults to TRUE. If TRUE, the function will convert the data to dates and qualifier to string vector.
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 connection is spotty. The default (NA) will set the limit to the maximum allowable limit for the service.
attach_request	logical, defaults to TRUE. If set to TRUE, the full request sent to the Water Data API is attached as an attribute to the data set.

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)

dataRetrieval documentation built on May 28, 2026, 9:06 a.m.