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
Defaulting to user installation because normal site-packages is not writeable
Requirement already satisfied: dataretrieval in /home/runner/.local/lib/python3.12/site-packages (0.1.dev1+gdc9b614f6)
Requirement already satisfied: requests in /usr/lib/python3/dist-packages (from dataretrieval) (2.31.0)
Requirement already satisfied: pandas<3.0.0,>=2.0.0 in /home/runner/.local/lib/python3.12/site-packages (from dataretrieval) (2.3.3)
Requirement already satisfied: numpy>=1.26.0 in /home/runner/.local/lib/python3.12/site-packages (from pandas<3.0.0,>=2.0.0->dataretrieval) (2.4.1)
Requirement already satisfied: python-dateutil>=2.8.2 in /usr/lib/python3/dist-packages (from pandas<3.0.0,>=2.0.0->dataretrieval) (2.8.2)
Requirement already satisfied: pytz>=2020.1 in /usr/lib/python3/dist-packages (from pandas<3.0.0,>=2.0.0->dataretrieval) (2024.1)
Requirement already satisfied: tzdata>=2022.7 in /home/runner/.local/lib/python3.12/site-packages (from pandas<3.0.0,>=2.0.0->dataretrieval) (2025.3)
Load the package so you can use it along with other packages used in this notebook.
[2]:
from dataretrieval import nwis
from IPython.display import display
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]:
pennsylvania = nwis.get_water_use(state='PA')
print('Retrieved ' + str(len(pennsylvania[0])) + ' water use records.')
Retrieved 55 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])
| <!DOCTYPE html> | |
|---|---|
| 0 | <head> |
| 1 | <meta charset="UTF-8" /> |
| 2 | <meta name="viewport" content="width=devic... |
| 3 | <link rel="icon" href="/nwaa-data/assets/f... |
| 4 | <title>U.S. Geological Survey</title> |
| 5 | <meta name="description" content=""> |
| 6 | <!-- |
| 7 | NWDC Google Tag Manager |
| 8 | - NWDC Pixel |
| 9 | - DAP Pixel |
| 10 | --> |
| 11 | <script>(function(w,d,s,l,i){w[l]=w[l]||[]... |
| 12 | new Date().getTime(),event:'gtm.js'});va... |
| 13 | j=d.createElement(s),dl=l!='dataLayer'?'... |
| 14 | 'https://www.googletagmanager.com/gtm.js... |
| 15 | })(window,document,'script','dataLayer',... |
| 16 | </script> |
| 17 | <!-- End Google Tag Manager --> |
| 18 | <!-- CHS Google Tag Manager --> |
| 19 | <script>(function(w,d,s,l,i){w[l]=w[l]||[]... |
| 20 | new Date().getTime(),event:'gtm.js'});va... |
| 21 | j=d.createElement(s),dl=l!='dataLayer'?'... |
| 22 | 'https://www.googletagmanager.com/gtm.js... |
| 23 | })(window,document,'script','dataLayer',... |
| 24 | </script> |
| 25 | <!-- End Google Tag Manager --> |
| 26 | <!-- START Google Font - Source Sans Pro --> |
| 27 | <link rel="preconnect" href="https://fon... |
| 28 | <link rel="preconnect" href="https://fon... |
| 29 | <link href="https://fonts.googleapis.com... |
| 30 | <!-- END Google Font - Source Sans Pro --> |
| 31 | <script type="module" crossorigin src="/nw... |
| 32 | <link rel="stylesheet" href="/nwaa-data/as... |
| 33 | </head> |
| 34 | <body> |
| 35 | <!-- NWDC Google Tag Manager (noscript) --> |
| 36 | <noscript> |
| 37 | <iframe src="https://www.googletagmanage... |
| 38 | height="0" width="0" style="display:no... |
| 39 | </iframe> |
| 40 | </noscript> |
| 41 | <!-- End Google Tag Manager (noscript) --> |
| 42 | <!-- Google Tag Manager (noscript) --> |
| 43 | <noscript> |
| 44 | <iframe src="https://www.googletagmanage... |
| 45 | height="0" width="0" style="display:no... |
| 46 | </iframe> |
| 47 | </noscript> |
| 48 | <!-- End Google Tag Manager (noscript) --> |
| 49 | <link rel="stylesheet" href="/nwaa-data/as... |
| 50 | <div id="app"></div> |
| 51 | <script src="/nwaa-data/assets/uswds/js/us... |
| 52 | <script src="/nwaa-data/assets/uswds/js/us... |
| 53 | </body> |
| 54 | </html> |
Show the data types of the columns in the resulting data frame.
[5]:
print(pennsylvania[0].dtypes)
<!DOCTYPE html> object
dtype: object
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]:
ohio = nwis.get_water_use(years=[2000, 2005, 2010], state='OH')
print('Retrieved ' + str(len(ohio[0])) + ' water use records.')
display(ohio[0])
Retrieved 55 water use records.
| <!DOCTYPE html> | |
|---|---|
| 0 | <head> |
| 1 | <meta charset="UTF-8" /> |
| 2 | <meta name="viewport" content="width=devic... |
| 3 | <link rel="icon" href="/nwaa-data/assets/f... |
| 4 | <title>U.S. Geological Survey</title> |
| 5 | <meta name="description" content=""> |
| 6 | <!-- |
| 7 | NWDC Google Tag Manager |
| 8 | - NWDC Pixel |
| 9 | - DAP Pixel |
| 10 | --> |
| 11 | <script>(function(w,d,s,l,i){w[l]=w[l]||[]... |
| 12 | new Date().getTime(),event:'gtm.js'});va... |
| 13 | j=d.createElement(s),dl=l!='dataLayer'?'... |
| 14 | 'https://www.googletagmanager.com/gtm.js... |
| 15 | })(window,document,'script','dataLayer',... |
| 16 | </script> |
| 17 | <!-- End Google Tag Manager --> |
| 18 | <!-- CHS Google Tag Manager --> |
| 19 | <script>(function(w,d,s,l,i){w[l]=w[l]||[]... |
| 20 | new Date().getTime(),event:'gtm.js'});va... |
| 21 | j=d.createElement(s),dl=l!='dataLayer'?'... |
| 22 | 'https://www.googletagmanager.com/gtm.js... |
| 23 | })(window,document,'script','dataLayer',... |
| 24 | </script> |
| 25 | <!-- End Google Tag Manager --> |
| 26 | <!-- START Google Font - Source Sans Pro --> |
| 27 | <link rel="preconnect" href="https://fon... |
| 28 | <link rel="preconnect" href="https://fon... |
| 29 | <link href="https://fonts.googleapis.com... |
| 30 | <!-- END Google Font - Source Sans Pro --> |
| 31 | <script type="module" crossorigin src="/nw... |
| 32 | <link rel="stylesheet" href="/nwaa-data/as... |
| 33 | </head> |
| 34 | <body> |
| 35 | <!-- NWDC Google Tag Manager (noscript) --> |
| 36 | <noscript> |
| 37 | <iframe src="https://www.googletagmanage... |
| 38 | height="0" width="0" style="display:no... |
| 39 | </iframe> |
| 40 | </noscript> |
| 41 | <!-- End Google Tag Manager (noscript) --> |
| 42 | <!-- Google Tag Manager (noscript) --> |
| 43 | <noscript> |
| 44 | <iframe src="https://www.googletagmanage... |
| 45 | height="0" width="0" style="display:no... |
| 46 | </iframe> |
| 47 | </noscript> |
| 48 | <!-- End Google Tag Manager (noscript) --> |
| 49 | <link rel="stylesheet" href="/nwaa-data/as... |
| 50 | <div id="app"></div> |
| 51 | <script src="/nwaa-data/assets/uswds/js/us... |
| 52 | <script src="/nwaa-data/assets/uswds/js/us... |
| 53 | </body> |
| 54 | </html> |
Example 3: Retrieve two specific water use categories for an entire state
[7]:
# Get water use data for livestock (LI) and irrigation (IT)
kansas = nwis.get_water_use(state='KS', categories=['IT', 'LI'])
print('Retrieved ' + str(len(kansas[0])) + ' water use records.')
display(kansas[0])
Retrieved 55 water use records.
| <!DOCTYPE html> | |
|---|---|
| 0 | <head> |
| 1 | <meta charset="UTF-8" /> |
| 2 | <meta name="viewport" content="width=devic... |
| 3 | <link rel="icon" href="/nwaa-data/assets/f... |
| 4 | <title>U.S. Geological Survey</title> |
| 5 | <meta name="description" content=""> |
| 6 | <!-- |
| 7 | NWDC Google Tag Manager |
| 8 | - NWDC Pixel |
| 9 | - DAP Pixel |
| 10 | --> |
| 11 | <script>(function(w,d,s,l,i){w[l]=w[l]||[]... |
| 12 | new Date().getTime(),event:'gtm.js'});va... |
| 13 | j=d.createElement(s),dl=l!='dataLayer'?'... |
| 14 | 'https://www.googletagmanager.com/gtm.js... |
| 15 | })(window,document,'script','dataLayer',... |
| 16 | </script> |
| 17 | <!-- End Google Tag Manager --> |
| 18 | <!-- CHS Google Tag Manager --> |
| 19 | <script>(function(w,d,s,l,i){w[l]=w[l]||[]... |
| 20 | new Date().getTime(),event:'gtm.js'});va... |
| 21 | j=d.createElement(s),dl=l!='dataLayer'?'... |
| 22 | 'https://www.googletagmanager.com/gtm.js... |
| 23 | })(window,document,'script','dataLayer',... |
| 24 | </script> |
| 25 | <!-- End Google Tag Manager --> |
| 26 | <!-- START Google Font - Source Sans Pro --> |
| 27 | <link rel="preconnect" href="https://fon... |
| 28 | <link rel="preconnect" href="https://fon... |
| 29 | <link href="https://fonts.googleapis.com... |
| 30 | <!-- END Google Font - Source Sans Pro --> |
| 31 | <script type="module" crossorigin src="/nw... |
| 32 | <link rel="stylesheet" href="/nwaa-data/as... |
| 33 | </head> |
| 34 | <body> |
| 35 | <!-- NWDC Google Tag Manager (noscript) --> |
| 36 | <noscript> |
| 37 | <iframe src="https://www.googletagmanage... |
| 38 | height="0" width="0" style="display:no... |
| 39 | </iframe> |
| 40 | </noscript> |
| 41 | <!-- End Google Tag Manager (noscript) --> |
| 42 | <!-- Google Tag Manager (noscript) --> |
| 43 | <noscript> |
| 44 | <iframe src="https://www.googletagmanage... |
| 45 | height="0" width="0" style="display:no... |
| 46 | </iframe> |
| 47 | </noscript> |
| 48 | <!-- End Google Tag Manager (noscript) --> |
| 49 | <link rel="stylesheet" href="/nwaa-data/as... |
| 50 | <div id="app"></div> |
| 51 | <script src="/nwaa-data/assets/uswds/js/us... |
| 52 | <script src="/nwaa-data/assets/uswds/js/us... |
| 53 | </body> |
| 54 | </html> |