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) orwu-irrigation-wd(irrigation withdrawals). Available models include:model
description
wu-public-supply-wdpublic-supply withdrawals
wu-public-supply-cupublic-supply consumptive use
wu-irrigation-wdirrigation withdrawals
wu-irrigation-cuirrigation consumptive use
wu-thermoelectricthermoelectric-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.
stateaccepts a full name ("Kansas"), a two-letter postal code ("KS"), or a two-digit FIPS code ("20");countytakes a five-digit FIPS code; and ahuccode’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_idto a HUC12 boundary layer (for example withgeopandas) lets you map the results.Pick one selector. Use exactly one of
state,county(five-digit FIPS), orhuc. 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
limitHUC12s (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_monthcolumn; annual data (annualcyorannualwy) come back with ayearcolumn.