header_tag.html

Skip to contents

Get NGWMN Water Level Data

Source: R/read_ngwmn_water_level.R
read_ngwmn_water_level.Rd

Water Level Observations data

Usage

read_ngwmn_water_level(
  monitoring_location_id = NA_character_,
  monitoring_location_obs_number = NA_character_,
  sample_time = NA_character_,
  data_provided_by = NA_character_,
  water_depth_below_land_surface_ft = NA_character_,
  water_level_above_site_datum_ft = NA_character_,
  monitoring_location_vertical_datum = NA_character_,
  water_level_above_navd88_ft = NA_character_,
  properties = NA_character_,
  datetime = NA_character_,
  ...,
  convertType = getOption("dataRetrieval.convertType"),
  no_paging = getOption("dataRetrieval.no_paging"),
  chunk_size = getOption("dataRetrieval.site_chunk_size_data"),
  limit = getOption("dataRetrieval.limit"),
  attach_request = getOption("dataRetrieval.attach_request")
)

Arguments

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.

monitoring_location_obs_number

Number of observation for given site. A list of values can be passed for this field, seperated by commas.

sample_time

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.

data_provided_by

Code for the agency or organization that provides, collects, owns, and/or manages the water level measurement record.

water_depth_below_land_surface_ft

Calculated depth to water in feet.

water_level_above_site_datum_ft

Water-level value represented as depth to site datum in feet.

monitoring_location_vertical_datum

Code indicating the vertical datum.

water_level_above_navd88_ft

Mediated water-level value represented as depth to water relative to the NAVD88 datum.

properties

A vector of requested columns to be returned from the query. Available options are: agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, sample_time, orig_unit, orig_value, accuracy_unit, accuracy_value, obs_datum_cd, obs_comment, obs_method, data_provided_by, water_depth_below_land_surface_ft, water_level_above_site_datum_ft, monitoring_location_vertical_datum, water_level_above_navd88_ft. The default (NA) will return all columns of the data.

datetime

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.

...

Not used. Included to help differentiate official Water Data API arguments from more seldom used, optional dataRetrieval-specific arguments.

convertType

logical, defaults to TRUE. If TRUE, the function will convert the data to dates, any qualifiers to string vector and reorder the returned data frame.

no_paging

logical, defaults to FALSE. If TRUE, the data will be requested from a native csv format. This can be dangerous because the data will cut off at 50,000 rows without indication that more data is available. Use TRUE with caution.

chunk_size

Number of monitoring_location_ids to chunk requests into. The default for functions that don't generally return long-term data records is 250, while the default for time series functions is 10. Setting to NA will eliminate site chunking, giving users full control.

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{
site <- "USGS-272838082142201"
ngwmn_wl <- read_ngwmn_water_level(monitoring_location_id = site)
#> Requesting:
#> https://api.waterdata.usgs.gov/ngwmn/ogcapi/collections/waterLevelObs/items?f=json&lang=en-US&monitoring_location_id=USGS-272838082142201&limit=50000
#> ⠙ iterating 1 done (0.27/s) | 3.8s
#> Remaining requests this hour:2162 

ngwmn_wl_sub <- read_ngwmn_water_level(monitoring_location_id = site,
                     monitoring_location_obs_number = 1:5)
#> Requesting:
#> https://api.waterdata.usgs.gov/ngwmn/ogcapi/collections/waterLevelObs/items?f=json&lang=en-US&limit=50000&monitoring_location_id=USGS-272838082142201
#> Remaining requests this hour:2160 

ngwml_wl_time2 <- read_ngwmn_water_level(monitoring_location_id = site,
                     datetime = c("2022-01-01", "2024-01-01"))
#> Requesting:
#> https://api.waterdata.usgs.gov/ngwmn/ogcapi/collections/waterLevelObs/items?f=json&lang=en-US&monitoring_location_id=USGS-272838082142201&datetime=2022-01-01T00%3A00%3A00Z%2F2024-01-01T00%3A00%3A00Z&limit=50000
#> Remaining requests this hour:2160 

sites <- c("USGS-272838082142201", "USGS-404159100494601",
           "USGS-401216080362703", "MBMG-702934")
ngwml_wl_sites <- read_ngwmn_water_level(monitoring_location_id = sites)
#> 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,MBMG-702934&limit=50000
#> ⠙ iterating 1 done (0.17/s) | 6s
#> Remaining requests this hour:2159 

# }