USGS dataretrieval Python Package Water-Use Examples

This notebook provides examples of using the Python dataretrieval package to retrieve water-use data from the USGS National Water Availability Assessment Data Companion (NWDC). The NWDC serves national-scale, modeled water-use estimates on a HUC12 (12-digit hydrologic unit) grid, queryable for any county, state, or hydrologic unit. It is the modern replacement for the retired legacy water-use service.

The dataretrieval package exposes the service through a single function, nwdc.get_wateruse, which returns a tuple of a pandas data frame and an associated metadata object.

Install the Package

Use the following code to install the package if it doesn’t exist already within your Jupyter Python environment.

[1]:
!pip install dataretrieval
Requirement already satisfied: dataretrieval in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (0.1.dev1+g55e94617b)
Requirement already satisfied: httpx in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from dataretrieval) (0.28.1)
Requirement already satisfied: pandas<4.0.0,>=2.0.0 in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from dataretrieval) (3.1.1)
Requirement already satisfied: anyio>=4.0 in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from dataretrieval) (4.16.0)
Requirement already satisfied: numpy>=2.0.2 in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from pandas<4.0.0,>=2.0.0->dataretrieval) (2.5.5)
Requirement already satisfied: python-dateutil>=2.9.0 in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from pandas<4.0.0,>=2.0.0->dataretrieval) (4.0.0)
Requirement already satisfied: idna>=2.8 in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from anyio>=4.0->dataretrieval) (3.20)
Requirement already satisfied: typing_extensions>=4.16.0 in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from anyio>=4.0->dataretrieval) (4.16.0)
Requirement already satisfied: tzdata in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from python-dateutil>=2.9.0->pandas<4.0.0,>=2.0.0->dataretrieval) (2026.6)
Requirement already satisfied: certifi in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (2026.10.23)
Requirement already satisfied: httpcore==1.* in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (1.0.9)
Requirement already satisfied: h11>=0.16 in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from httpcore==1.*->httpx->dataretrieval) (0.16.0)

Load the package so you can use it along with other packages used in this notebook.

[2]:
from IPython.display import display

from dataretrieval import nwdc

Basic Usage

This example uses the get_wateruse() function to retrieve modeled water-use estimates. The following arguments are commonly used:

  • model (string): The water-use category to query, for example wu-public-supply-wd (public-supply withdrawals) or wu-irrigation-wd (irrigation withdrawals). Available models 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

  • variable (string or list of strings): One or more variable IDs within the chosen model, for example pswdtot (total public-supply withdrawals) or ["pswdgw", "pswdsw"] for the groundwater and surface-water components. The service requires at least one variable.

  • state, county, or huc (string, int, or list): Exactly one of these selects the area. state accepts a full name ("Kansas"), a two-letter postal code ("KS"), or a two-digit FIPS code ("20"); county takes a five-digit FIPS code; and a huc code’s length sets its hydrologic-unit level.

  • time_resolution (string): "monthly", "annualcy" (annual, calendar year), or "annualwy" (annual, water year).

  • start_date, end_date (string): The query window, formatted "YYYY" for annual data or "YYYY-MM" for monthly data.

See the NWDC data catalog for the full list of models and their variables.

Example 1: Retrieve public-supply withdrawals for a state

Request total public-supply withdrawals for every HUC12 in Kansas, as annual calendar-year values. Because a state spans many HUC12s, the service returns the result across several pages; get_wateruse() follows the pagination links and stitches the pages into one frame.

[3]:
kansas, md = nwdc.get_wateruse(
    model="wu-public-supply-wd",
    variable="pswdtot",
    state="KS",
    start_date="2015",
    end_date="2020",
    time_resolution="annualcy",
)
print(
    "Retrieved "
    + str(len(kansas))
    + " records across "
    + str(kansas["huc12_id"].nunique())
    + " HUC12 watersheds."
)
Retrieving: nwdc · 4 pages · 12,342 rows · 97/100 requests remaining
Retrieved 12342 records across 2057 HUC12 watersheds.

Interpreting the Result

The get_wateruse() function returns a tuple containing a pandas data frame and an associated metadata object. The data frame is in long (tidy) form: one row per HUC12 and time step. 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.

Once you’ve got the data frame, there are several useful things you can do to explore the data.

[4]:
# Display the data frame as a table
display(kansas)
huc12_id year pswdtot_mgd
0 102400050904 2015 0.073444
1 102400050904 2016 0.078557
2 102400050904 2017 0.080606
3 102400050904 2018 0.082575
4 102400050904 2019 0.079965
... ... ... ...
12337 111001020405 2016 0.000000
12338 111001020405 2017 0.000000
12339 111001020405 2018 0.000000
12340 111001020405 2019 0.000000
12341 111001020405 2020 0.000000

12342 rows × 3 columns

Show the data types of the columns in the resulting data frame.

[5]:
print(kansas.dtypes)
huc12_id           str
year             int64
pswdtot_mgd    float64
dtype: object

Aggregate the HUC12 grid to a statewide total for each year.

[6]:
statewide = kansas.groupby("year")["pswdtot_mgd"].sum()
display(statewide)
year
2015    439.200621
2016    430.236690
2017    438.934380
2018    446.582559
2019    435.360573
2020    422.042980
Name: pswdtot_mgd, dtype: float64

The other part of the result returned from the get_wateruse() function is a metadata object that contains information about the query that was executed to return the data. For example, you can access the URL that was assembled to retrieve the requested data from the NWDC.

[7]:
print("The query URL used to retrieve the data from the NWDC was: " + md.url)
The query URL used to retrieve the data from the NWDC was: https://api.water.usgs.gov/nwaa-data/data?format=csv&model=wu-public-supply-wd&variable=pswdtot&timeres=annualcy&startdate=2015&enddate=2020&intersection=overlap&limit=600&location=stateCd%3AKS

Additional Examples

Example 2: Split public-supply withdrawals by source

Request the total, groundwater, and surface-water components of public-supply withdrawals for Rhode Island as monthly values for 2020. Passing a list of variables returns one value column per variable.

[8]:
rhode_island, md = nwdc.get_wateruse(
    model="wu-public-supply-wd",
    variable=["pswdtot", "pswdgw", "pswdsw"],
    state="RI",
    start_date="2020-01",
    end_date="2020-12",
    time_resolution="monthly",
)
display(rhode_island)
Retrieving: nwdc · 1 page · 744 rows · 96/100 requests remaining
huc12_id year_month pswdtot_mgd pswdgw_mgd pswdsw_mgd
0 010900020502 2020-01 0.831363 0.000000 0.831363
1 010900020502 2020-02 0.897799 0.000000 0.897799
2 010900020502 2020-03 0.832903 0.000000 0.832903
3 010900020502 2020-04 0.855845 0.000000 0.855845
4 010900020502 2020-05 0.983631 0.000000 0.983631
... ... ... ... ... ...
739 020302030000 2020-08 0.111719 0.016508 0.095210
740 020302030000 2020-09 0.100406 0.014826 0.085580
741 020302030000 2020-10 0.088145 0.012869 0.075276
742 020302030000 2020-11 0.083046 0.011761 0.071285
743 020302030000 2020-12 0.078484 0.011041 0.067443

744 rows × 5 columns

Example 3: Retrieve a different water-use category

Swap the model and variable to retrieve irrigation withdrawals instead of public supply. Here we request total irrigation withdrawals (irrwdtot) for Nebraska as annual calendar-year values.

[9]:
nebraska, md = nwdc.get_wateruse(
    model="wu-irrigation-wd",
    variable="irrwdtot",
    state="NE",
    start_date="2015",
    end_date="2020",
    time_resolution="annualcy",
)
display(nebraska)
Retrieving: nwdc · 4 pages · 12,630 rows · 94/100 requests remaining
huc12_id year irrwdtot_mgd
0 101201060401 2015 0.000000
1 101201060401 2016 0.000000
2 101201060401 2017 0.000000
3 101201060401 2018 0.000000
4 101201060401 2019 0.000000
... ... ... ...
12625 102702070502 2016 0.258933
12626 102702070502 2017 1.470690
12627 102702070502 2018 0.712772
12628 102702070502 2019 0.248589
12629 102702070502 2020 0.388215

12630 rows × 3 columns

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 (five-digit FIPS), or huc. Each selector also accepts a list (e.g. state=["NE", "KS"]), 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.

  • Time columns. Monthly data come back with a year_month column; annual data (annualcy or annualwy) come back with a year column.