dataretrieval.wateruse

Retrieve USGS water-use data from the NWDC web service.

The National Water Availability Assessment Data Companion (NWDC) web services provide national-scale, USGS-modeled water-use data that underlie the USGS National Water Availability Assessment. Estimates are served on a HUC12 (12-digit hydrologic unit) spatial grid and can be queried for any county, state, or hydrologic unit. This is the modern replacement for the defunct legacy NWIS water-use service (nwis.get_water_use).

Unlike the main Water Data getters (dataretrieval.waterdata) and NGWMN (dataretrieval.ngwmn), the NWDC is a plain CSV REST service rather than an OGC API Features collection. This module supplies the NWDC-specific bits — request building, CSV parsing, the Link-header cursor, and the {detail} error envelope. The service-neutral transport layer supplies cursor pagination, response aggregation, client lifecycle, and sync-from-async dispatch. The module follows the same conventions: host-scoped request headers, the typed DataRetrievalError taxonomy, and a (DataFrame, BaseMetadata) return.

See https://api.water.usgs.gov/docs/nwaa-data/ for the API reference and https://water.usgs.gov/nwaa-data/ for the catalog of available models and variables.

Examples

from dataretrieval import wateruse

# Monthly public-supply withdrawals for Rhode Island, 2020 onward.
df, md = wateruse.get_wateruse(
    model="wu-public-supply-wd",
    variable=["pswdtot", "pswdgw", "pswdsw"],
    state="RI",
    start_date="2020-01",
    time_resolution="monthly",
)
dataretrieval.wateruse.DEFAULT_CONCURRENT_REQUESTS = 4

This service’s preferred in-flight cap when API_USGS_CONCURRENT is unset. Lower than the package default of 32 because every location retries independently, so a rate-limit episode bursts this number times the retry count; the NWDC tolerates this level without rate-limit errors (verified by stress test) and higher has not been tested. Setting API_USGS_CONCURRENT overrides it – see dataretrieval.transport.fanout._resolve_concurrency() for why the general setting outranks a module’s default rather than the reverse.

dataretrieval.wateruse.MODELS = ('wu-public-supply-wd', 'wu-public-supply-cu', 'wu-thermoelectric', 'wu-irrigation-wd', 'wu-irrigation-cu')

Water-use models (categories) served by the NWDC. The catalog at https://water.usgs.gov/nwaa-data/ lists the variables available within each.

dataretrieval.wateruse.TIME_RESOLUTIONS = ('monthly', 'annualcy', 'annualwy')

monthly, annual calendar year, annual water year.

Type:

Temporal resolutions

dataretrieval.wateruse.get_wateruse(model: str, variable: str | Iterable[str] | None = None, state: str | int | Iterable[str | int] | None = None, county: str | Iterable[str] | None = None, huc: str | Iterable[str] | None = None, time_resolution: str | None = None, start_date: str | None = None, end_date: str | None = None, intersection: str = 'overlap', limit: int = 600, ssl_check: bool = True) → tuple[DataFrame, BaseMetadata][source]

Get USGS water-use data from the NWDC web service.

Retrieves modeled water-use estimates from the USGS National Water Availability Assessment Data Companion. The area is given as exactly one of state, county, or huc; results are always returned on a HUC12 grid, in a long (tidy) frame with one row per HUC12 and time step. Large areas (e.g. a whole region or a populous state) are served across multiple pages; this function follows those pages transparently and concatenates them into one frame.

Each selector also accepts a list of values. The NWDC queries one area per request, so a list is fanned out into one request per value — up to API_USGS_CONCURRENT in parallel, defaulting to DEFAULT_CONCURRENT_REQUESTS for this service — and the results are concatenated in the order given. A fan-out interrupted by a rate limit or an upstream fault raises a resumable FanOutInterrupted, whose .call.resume() re-issues only the locations that did not complete.

Parameters:

  • model (string) – Water-use category to query. See MODELS for the available options (e.g. "wu-public-supply-wd"). The full catalog of models and their variables is at https://water.usgs.gov/nwaa-data/.

  • variable (string or iterable of strings, optional) – One or more variable IDs within model (e.g. "pswdtot" for total public-supply withdrawals, or ["pswdgw", "pswdsw"] for the groundwater and surface-water components). Multiple variables are comma-joined into a single request. The service requires at least one variable; omitting it returns a 400 listing the model’s valid variable IDs (surfaced as a DataRetrievalError).

  • state (string, int, or iterable, optional) – One or more US states/territories to query. Each accepts a full name ("Wisconsin"), a two-letter postal code ("WI"), or a two-digit ANSI/FIPS code ("55" or 55), mirroring dataretrieval.ngwmn.get_sites().

  • county (string or iterable, optional) – One or more five-digit county FIPS codes — state FIPS + county FIPS, e.g. "55025" for Dane County, Wisconsin.

  • huc (string or iterable, optional) –

    One or more hydrologic unit codes. Each code’s level is taken from its length: a 2-digit code queries a HUC2 region, 8-digit a HUC8 subbasin, 12-digit a single HUC12, and so on (even lengths 2-12, e.g. "04", "07070005", "010900020502").

    Provide exactly one of state, county, or huc (each may be a single value or a list).

  • time_resolution (string, optional) – Temporal resolution: "monthly", "annualcy" (annual, calendar year), or "annualwy" (annual, water year). See TIME_RESOLUTIONS.

  • start_date (string, optional) – Start of the query window, formatted "YYYY" for annual data or "YYYY-MM" for monthly data.

  • end_date (string, optional) – End of the query window, in the same format as start_date.

  • intersection (string, optional) – How to select HUC12s that straddle the queried-area boundary: "overlap" (any overlap, the default) or "envelop" (fully enclosed).

  • limit (int, optional) – Maximum number of HUC12s returned per page. Queries spanning more than limit HUC12s are split across pages and reassembled. Default 600.

  • ssl_check (bool, optional) – If True (default), verify SSL certificates; set False to skip verification (e.g. behind a TLS-intercepting proxy).

Returns:

  • df (pandas.DataFrame) – Water-use estimates in long form: a huc12_id column (string, leading zeros preserved), a time column (year_month for monthly data or year for annual data), and one value column per requested variable (suffixed with its unit, e.g. pswdtot_mgd for million gallons per day).

  • md (dataretrieval.utils.BaseMetadata) – Metadata describing the request (URL, query time, response headers).

Raises:

  • ValueError – If not exactly one of state, county, or huc is given, or a given selector is malformed (an unrecognized state, a county code that is not five digits, or a HUC of invalid length).

  • DataRetrievalError – On an HTTP error response, the typed subclass for the status (see dataretrieval.exceptions.error_for_status()). A transient 429, 5xx, or recoverable connection failure that exhausts inline retries is raised as a resumable FanOutInterrupted; a deterministic connection failure (for example, a permanently unresolvable host) remains a NetworkError.

Examples

>>> from dataretrieval import wateruse
>>> df, md = wateruse.get_wateruse(
...     model="wu-public-supply-wd",
...     variable=["pswdtot", "pswdgw", "pswdsw"],
...     state="RI",
...     start_date="2020-01",
...     time_resolution="monthly",
... )