USGS Water-Use Data (NWDC)

The USGS National Water Availability Assessment Data Companion (NWDC) serves national-scale, modeled water-use estimates that underlie the USGS National Water Availability Assessment. Estimates are produced on a HUC12 (12-digit hydrologic unit) grid and can be queried for any county, state, or hydrologic unit. They are the modern replacement for the retired legacy NWIS water-use service.

dataretrieval exposes the service through a single function, nwdc.get_wateruse, which returns a tidy pandas.DataFrame plus a metadata object. Available models (categories) include:

model

description

wu-public-supply-wd

public-supply withdrawals

wu-public-supply-cu

public-supply consumptive use

wu-irrigation-wd

irrigation withdrawals

wu-irrigation-cu

irrigation consumptive use

wu-thermoelectric

thermoelectric-power water use

Each model exposes its own set of variables; see the NWDC data catalog for the full list.

A motivating question

Where does Wisconsin’s public water supply come from — groundwater or surface water — and when through the year is demand highest?

Answering it is a typical water-use workflow: pull a state’s monthly withdrawals split by source, aggregate the HUC12 grid to a statewide time series, and look at the seasonal cycle and the groundwater/surface-water split.

[1]:
%matplotlib inline

import matplotlib.pyplot as plt
import pandas as pd

from dataretrieval import nwdc

1. Retrieve the data

We request three variables for the public-supply-withdrawals model: pswdtot (total), pswdgw (groundwater source), and pswdsw (surface-water source), for every HUC12 in Wisconsin, monthly, for calendar year 2020.

Wisconsin spans more HUC12s than fit on a single page, so the service returns the result across several pages — get_wateruse follows the pagination links and stitches the pages into one frame for you.

[2]:
df, md = nwdc.get_wateruse(
    model="wu-public-supply-wd",
    variable=["pswdtot", "pswdgw", "pswdsw"],
    state="WI",
    start_date="2020-01",
    end_date="2020-12",
    time_resolution="monthly",
)

print(f"{len(df):,} rows across {df['huc12_id'].nunique():,} HUC12 watersheds")
df.head()
Retrieving: nwdc · 4 pages · 21,684 rows · 89/100 requests remaining
21,684 rows across 1,807 HUC12 watersheds
[2]:
huc12_id year_month pswdtot_mgd pswdgw_mgd pswdsw_mgd
0 040102011601 2020-01 0.223875 0.022856 0.201019
1 040102011601 2020-02 0.241280 0.024077 0.217204
2 040102011601 2020-03 0.216031 0.022007 0.194024
3 040102011601 2020-04 0.228126 0.023354 0.204772
4 040102011601 2020-05 0.237859 0.024068 0.213790

The frame is in long (tidy) form: one row per HUC12 and month. The huc12_id column is kept as a string so leading zeros are preserved, and each value column carries its unit — here _mgd, million gallons per day.

2. Aggregate to a statewide monthly series

Summing across every HUC12 gives the statewide withdrawal for each month.

[3]:
statewide = df.groupby("year_month")[["pswdtot_mgd", "pswdgw_mgd", "pswdsw_mgd"]].sum()
statewide.index = pd.to_datetime(statewide.index)
statewide
[3]:
pswdtot_mgd pswdgw_mgd pswdsw_mgd
year_month
2020-01-01 435.828931 241.079916 194.749017
2020-02-01 463.772231 254.232782 209.539452
2020-03-01 434.692956 239.611969 195.080977
2020-04-01 455.904863 251.867757 204.037110
2020-05-01 477.426702 266.923754 210.502946
2020-06-01 545.854550 306.431839 239.422714
2020-07-01 567.777062 315.372850 252.404218
2020-08-01 549.757171 308.507553 241.249624
2020-09-01 506.739340 281.027019 225.712321
2020-10-01 437.006738 241.553234 195.453501
2020-11-01 446.476316 244.952029 201.524282
2020-12-01 432.453724 240.011665 192.442060

3. The seasonal demand cycle

Public-supply withdrawals peak in summer, when outdoor use (lawns, gardens, recreation) adds to baseline indoor demand.

[4]:
fig, ax = plt.subplots(figsize=(9, 4))
ax.plot(statewide.index, statewide["pswdtot_mgd"], marker="o", color="#1f77b4")
ax.set_title("Wisconsin public-supply withdrawals, 2020")
ax.set_ylabel("Withdrawal (million gallons/day)")
ax.set_xlabel("Month")
ax.grid(True, alpha=0.3)
fig.tight_layout()
../_images/examples_USGS_WaterUse_Examples_8_0.png

4. Groundwater vs. surface water

Because total withdrawal is the sum of its groundwater and surface-water components, a stacked area shows how each source contributes through the year.

[5]:
gw_share = statewide["pswdgw_mgd"].sum() / statewide["pswdtot_mgd"].sum()
print(f"Groundwater supplies {gw_share:.0%} of Wisconsin's public water supply")

fig, ax = plt.subplots(figsize=(9, 4))
ax.stackplot(
    statewide.index,
    statewide["pswdgw_mgd"],
    statewide["pswdsw_mgd"],
    labels=["Groundwater", "Surface water"],
    colors=["#8c6d31", "#1f77b4"],
    alpha=0.85,
)
ax.set_title("Source of Wisconsin public-supply withdrawals, 2020")
ax.set_ylabel("Withdrawal (million gallons/day)")
ax.set_xlabel("Month")
ax.legend(loc="upper left")
fig.tight_layout()
Groundwater supplies 55% of Wisconsin's public water supply
../_images/examples_USGS_WaterUse_Examples_10_1.png

Notes

  • Spatial resolution. Estimates are always returned on the HUC12 grid, regardless of the area you query. Joining huc12_id to a HUC12 boundary layer (for example with geopandas) lets you map the results.

  • Pick one selector. Use exactly one of state, county (5-digit FIPS), or huc. state accepts a name, postal code, or FIPS; a huc code’s length sets its level (huc="04" → HUC2, huc="07070005" → HUC8). Each selector also accepts a list (e.g. state=["WI", "MN"]), fanned out into one request per area and concatenated.

  • Large areas paginate. A query spanning more than limit HUC12s (600 by default) is split across pages; get_wateruse follows the links and returns a single concatenated frame. Whole-region queries (e.g. huc="04") may return many pages and take longer.

  • Annual data. Set time_resolution="annualcy" (calendar year) or "annualwy" (water year) and use four-digit years for start_date/end_date; the time column comes back as year instead of year_month.

  • Other models. Swap model and variable to retrieve irrigation (wu-irrigation-wd) or thermoelectric (wu-thermoelectric) water use. See the NWDC data catalog for the variables available in each.