USGS dataretrieval Python Package `get_water_use()` Examples

This notebook provides examples of using the Python dataretrieval package to retrieve water use data. The dataretrieval package provides a collection of functions to get data from the USGS National Water Information System (NWIS) and other online sources of hydrology and water quality data, including the United States Environmental Protection Agency (USEPA).

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.12/x64/lib/python3.13/site-packages (0.1.dev1+g0aec2c864)
Requirement already satisfied: requests in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from dataretrieval) (2.33.1)
Requirement already satisfied: pandas<4.0.0,>=2.0.0 in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from dataretrieval) (3.0.2)
Requirement already satisfied: numpy>=1.26.0 in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from pandas<4.0.0,>=2.0.0->dataretrieval) (2.4.4)
Requirement already satisfied: python-dateutil>=2.8.2 in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from pandas<4.0.0,>=2.0.0->dataretrieval) (2.9.0.post0)
Requirement already satisfied: six>=1.5 in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from python-dateutil>=2.8.2->pandas<4.0.0,>=2.0.0->dataretrieval) (1.17.0)
Requirement already satisfied: charset_normalizer<4,>=2 in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from requests->dataretrieval) (3.4.7)
Requirement already satisfied: idna<4,>=2.5 in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from requests->dataretrieval) (3.11)
Requirement already satisfied: urllib3<3,>=1.26 in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from requests->dataretrieval) (2.6.3)
Requirement already satisfied: certifi>=2023.5.7 in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from requests->dataretrieval) (2026.2.25)

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 nwisfrom dataretrieval import waterdata
import dataretrieval.waterdata as waterdata

  Cell In[2], line 3
    from dataretrieval import nwisfrom dataretrieval import waterdata
                                       ^
SyntaxError: invalid syntax

Basic Usage

The dataretrieval package has several functions that allow you to retrieve data from different web services. This examples uses the get_water_use() function to retrieve water use data. The following arguments are supported:

Arguments (Additional arguments, if supplied, will be used as query parameters)

years (Listlike): List or comma delimited string of years. Must be years ending in 0 or 5 because water use data is only reported during these years, or “ALL”, which retrieves all available years
state (string): Full name, abbreviation or id for a state for which to retrieve data
county (string or list of strings): County IDs from county lookup or “ALL”
categories (Listlike): List or comma delimited string of two-letter category abbreviations

Example 1: Retrieve all water use data for a state

[3]:

# [Defunct] pennsylvania = nwis.get_water_use(state="PA")
# [Defunct] print("Retrieved " + str(len(pennsylvania[0])) + " water use records.")

Interpreting the Result

The result of calling the get_water_use() function is an object that contains a Pandas data frame object and an associated metadata object. The Pandas data frame contains the water use data.

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

Display the data frame as a table. The example request was for a whole state. The data returned are organized by county and year, with summary data reported every 5 years.

[4]:

display(pennsylvania[0])

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[4], line 1
----> 1 display(pennsylvania[0])

NameError: name 'pennsylvania' is not defined

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

[5]:

print(pennsylvania[0].dtypes)

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[5], line 1
----> 1 print(pennsylvania[0].dtypes)

NameError: name 'pennsylvania' is not defined

Example 2: Retrieve data for an entire state for certain years

Returns data parsed by county - one row for each county for each year of interest rather than the entire state. Data are included for 5 year periods.

[6]:

# [Defunct] ohio = nwis.get_water_use(years=[2000, 2005, 2010], state="OH")
# [Defunct] print("Retrieved " + str(len(ohio[0])) + " water use records.")
# [Defunct] display(ohio[0])

Example 3: Retrieve two specific water use categories for an entire state

[7]:

# Get water use data for livestock (LI) and irrigation (IT)
# [Defunct] kansas = nwis.get_water_use(state="KS", categories=["IT", "LI"])
# [Defunct] print("Retrieved " + str(len(kansas[0])) + " water use records.")
# [Defunct] display(kansas[0])

USGS dataretrieval Python Package get_water_use() Examples