Generalized NGWMN API retrieval function

Function that allows complex CQL queries on National Groundwater Monitoring Network API. See https://api.waterdata.usgs.gov/docs/ogcapi/complex-queries/ for more information.

Usage

read_ngwmn(
  service,
  CQL = NA_character_,
  monitoring_location_id = NA_character_,
  ...,
  convertType = getOption("dataRetrieval.convertType"),
  limit = getOption("dataRetrieval.limit"),
  attach_request = getOption("dataRetrieval.attach_request")
)

Arguments

service

character, can be any existing collection. Can be: "providers", "constructionObs", "waterLevelObs", "sites", or "lithologyObs". The date of an observation. Date and time expressions adhere to RFC 3339. Intervals may be bounded or half-bounded (double-dots at start or end). Examples:

• A date-time: "2018-02-12T23:20:50-00:00"

• A bounded interval:"2018-02-12T00:00:00+05:00/2018-03-18T12:31:12+05:00"

• Half-bounded intervals: "2018-02-12T00:00:00-05:00/.." or "../2018-03-18T12:31:12-05:00"

Only features that have a sample_time that intersects the value of datetime are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties.

See also Details below for more information.

CQL

A string in a Common Query Language format.

monitoring_location_id

This field is required. Combined site identifier of agency code and site number (format of {agency_code}-{monitoring_location_number}). A list of values can be passed for this field, seperated by commas.

...

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

# \donttest{
cql <- '{
 "op": "between",
   "args": [
      { "property": "water_level_above_navd88_ft" },
      [ "100.00", "200.00" ]
   ]
}'

wl_data <- read_ngwmn(service = "waterLevelObs",
                      monitoring_location_id = c("USGS-272838082142201", 
                                                 "USGS-404159100494601", 
                                                 "USGS-401216080362703"),
                      CQL = cql)
#> Requesting:
#> https://api.waterdata.usgs.gov/ngwmn/ogcapi/collections/waterLevelObs/items?f=json&lang=en-US&monitoring_location_id=USGS-272838082142201,USGS-404159100494601,USGS-401216080362703&limit=50000
#> ⠙ iterating 1 done (0.29/s) | 3.4s
#> Remaining requests this hour:2171 

cql3 <- '{
"op": "and",
"args": [
 {
   "op": "between",
   "args": [
     { "property": "water_level_above_navd88_ft" },
     [ "100.00", "200.00" ]
   ]
 },
 {
   "op": "in",
   "args": [
     { "property": "monitoring_location_id" },
     [ "USGS-272838082142201", "USGS-404159100494601", "USGS-401216080362703" ]
   ]
 }
]
}'


wl_data_alt <- read_ngwmn(service = "waterLevelObs",
                          CQL = cql3)
#> Requesting:
#> https://api.waterdata.usgs.gov/ngwmn/ogcapi/collections/waterLevelObs/items?f=json&lang=en-US&monitoring_location_id=ALL&limit=50000
#> ⠙ iterating 1 done (0.28/s) | 3.6s
#> Remaining requests this hour:2169 

# }