Download Water Use model output from the NWAA Data Companion

Convenience wrapper for the Water Use (wu) family of NWAA models. Validates that model_id, variable_ids, and time_res are valid for this family before sending the request. County and state extents act as polygon selectors and return results at HUC12 resolution.

Usage

nwaa_water_use(
  model_id,
  variable_ids,
  location_type,
  location_id,
  time_res = "monthly",
  range = c("recent", "historical", "custom"),
  start = NULL,
  end = NULL,
  intersection = NULL,
  skip = 0,
  format = "csv",
  quiet = TRUE
)

Arguments

model_id: Water Use model ID. See nwaa_wu_models.
variable_ids: One or more variable IDs from the selected model. See nwaa_wu_variables.
location_type: Location type used by the API. See nwaa_location_types.
location_id: Identifier for the selected location_type (HUC code, lowercase 2-letter state abbreviation, or 5-digit county code).
time_res: Temporal resolution: "monthly", "annualwy" (water year), or "annualcy" (calendar year).
range: Date-range mode: "recent", "historical", or "custom".
start, end: For range = "custom" only. Monthly uses "YYYY-MM" and annual uses "YYYY".
intersection: Optional. Controls how polygon selectors include HUC12s when location_type is "statecd" or "countycd". See nwaa_intersection_types.
skip: Record offset for paging. Default 0.
format: Output format: "csv", "json", or "geojson". GeoJSON output requires the sf package.
quiet: If FALSE, prints the request URL and response content type.

Value

Parsed data. For format = "csv", a tibble. For format = "json", a list. For format = "geojson", an sf object.

Details

Learn options inside the package:

Models: nwaa_wu_models
Variables by model: nwaa_wu_variables
Location types: nwaa_location_types

The USGS NWAA Data Companion "Subset and Download" tool generates valid request URLs interactively and is a useful reference when composing queries.

Examples

# Discover models and variables (offline)
nwaa_wu_models()
#> # A tibble: 5 × 4
#>   model_id            model_label                                start_ym end_ym
#>   <chr>               <chr>                                      <chr>    <chr> 
#> 1 wu-irrigation-cu    Crop Irrigation Consumptive Water-Use Mod… 2000-01  2020-…
#> 2 wu-irrigation-wd    Crop Irrigation Withdrawals Water-Use Mod… 2000-01  2020-…
#> 3 wu-public-supply-cu Public Supply Consumptive Water-Use Model  2009-01  2020-…
#> 4 wu-public-supply-wd Public Supply Withdrawals Water-Use Model  2000-01  2020-…
#> 5 wu-thermoelectric   Thermoelectric Power Water-Use Model       2008-01  2020-…
nwaa_wu_variables("wu-irrigation-wd")
#> # A tibble: 3 × 4
#>   model_id         variable_id unit  variable_name                            
#>   <chr>            <chr>       <chr> <chr>                                    
#> 1 wu-irrigation-wd irrwdtot    mgd   Crop irrigation total withdrawals        
#> 2 wu-irrigation-wd irrwdgw     mgd   Crop irrigation groundwater withdrawals  
#> 3 wu-irrigation-wd irrwdsw     mgd   Crop irrigation surface-water withdrawals

# \donttest{
# County selector, annual water-year, custom range
df <- nwaa_water_use(
  model_id = "wu-irrigation-wd",
  variable_ids = c("irrwdgw", "irrwdsw", "irrwdtot"),
  location_type = "countycd",
  location_id = "06029",
  time_res = "annualwy",
  range = "custom",
  start = "2001",
  end = "2020",
  intersection = "overlap",
  format = "csv",
  quiet = FALSE
)
#> URL: https://api.water.usgs.gov/nwaa-data/data?model=wu-irrigation-wd&location=countycd%3A06029&format=csv&variable=irrwdgw%2Cirrwdsw%2Cirrwdtot&timeRes=annualwy&startDate=2001&endDate=2020&intersection=overlap&skip=0
#> Content-Type: text/csv

# HUC12 selector, most recent timepoint
df_recent <- nwaa_water_use(
  model_id = "wu-irrigation-wd",
  variable_ids = "irrwdtot",
  location_type = "huc12",
  location_id = "180300010602",
  time_res = "annualwy",
  range = "recent",
  format = "csv"
)

# Stricter polygon selection
df_envelop <- nwaa_water_use(
  model_id = "wu-irrigation-wd",
  variable_ids = c("irrwdgw", "irrwdsw", "irrwdtot"),
  location_type = "countycd",
  location_id = "06029",
  time_res = "annualwy",
  range = "custom",
  start = "2001",
  end = "2020",
  intersection = "envelop",
  format = "csv"
)
# }