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.10/site-packages (0.1.dev1+g3ba0c83)
Requirement already satisfied: requests in /home/runner/.local/lib/python3.10/site-packages (from dataretrieval) (2.32.3)
Requirement already satisfied: pandas==2.* in /home/runner/.local/lib/python3.10/site-packages (from dataretrieval) (2.2.3)
Requirement already satisfied: numpy>=1.22.4 in /home/runner/.local/lib/python3.10/site-packages (from pandas==2.*->dataretrieval) (2.1.2)
Requirement already satisfied: python-dateutil>=2.8.2 in /home/runner/.local/lib/python3.10/site-packages (from pandas==2.*->dataretrieval) (2.9.0.post0)
Requirement already satisfied: pytz>=2020.1 in /usr/lib/python3/dist-packages (from pandas==2.*->dataretrieval) (2022.1)
Requirement already satisfied: tzdata>=2022.7 in /home/runner/.local/lib/python3.10/site-packages (from pandas==2.*->dataretrieval) (2024.2)
Requirement already satisfied: charset-normalizer<4,>=2 in /home/runner/.local/lib/python3.10/site-packages (from requests->dataretrieval) (3.4.0)
Requirement already satisfied: idna<4,>=2.5 in /usr/lib/python3/dist-packages (from requests->dataretrieval) (3.3)
Requirement already satisfied: urllib3<3,>=1.21.1 in /usr/lib/python3/dist-packages (from requests->dataretrieval) (1.26.5)
Requirement already satisfied: certifi>=2017.4.17 in /usr/lib/python3/dist-packages (from requests->dataretrieval) (2020.6.20)
Requirement already satisfied: six>=1.5 in /usr/lib/python3/dist-packages (from python-dateutil>=2.8.2->pandas==2.*->dataretrieval) (1.16.0)
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 469 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])
| state_cd | state_name | county_cd | county_nm | year | Total Population total population of area in thousands | Public Supply population served by groundwater in thousands | Public Supply population served by surface water in thousands | Public Supply total population served in thousands | Public Supply self-supplied groundwater withdrawals fresh in Mgal/d | ... | Hydroelectric Power power generated by instream use in gigawatt-hours | Hydroelectric Power power generated by offstream use in gigawatt-hours | Hydroelectric Power total power generated in gigawatt-hours | Hydroelectric Power number of instream facilities | Hydroelectric Power number of offstream facilities | Hydroelectric Power total number of facilities | Wastewater Treatment returns by public wastewater facilities in Mgal/d | Wastewater Treatment number of public wastewater facilities | Wastewater Treatment number of wastewater facilities | Wastewater Treatment reclaimed wastewater released by wastewater facilities in Mgal/d | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 42 | Pennsylvania | 1 | Adams County | 1985 | 70.000 | 11.300 | 1.860 | 13.160 | 7.85 | ... | 0.00 | - | - | - | - | - | 2.86 | 18 | - | - |
| 1 | 42 | Pennsylvania | 1 | Adams County | 1990 | 78.270 | 21.920 | 9.520 | 31.440 | 2.44 | ... | 0.00 | - | - | 0 | - | - | 6.26 | 18 | - | - |
| 2 | 42 | Pennsylvania | 1 | Adams County | 1995 | 84.000 | 17.160 | 19.660 | 36.820 | 2.58 | ... | 0.00 | 0.00 | 0.00 | 0 | 0 | 0 | 3.00 | 4 | - | - |
| 3 | 42 | Pennsylvania | 1 | Adams County | 2000 | 91.290 | - | - | 45.928 | 2.48 | ... | - | - | - | - | - | - | - | - | - | - |
| 4 | 42 | Pennsylvania | 1 | Adams County | 2005 | 99.749 | 22.997 | 25.019 | 48.016 | 2.01 | ... | - | - | - | - | - | - | - | - | - | - |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 464 | 42 | Pennsylvania | 133 | York County | 1995 | 362.790 | 27.710 | 199.430 | 227.140 | 3.59 | ... | 112.58 | 0.00 | 112.58 | 1 | 0 | 1 | 32.95 | 9 | - | - |
| 465 | 42 | Pennsylvania | 133 | York County | 2000 | 381.750 | - | - | 285.291 | 3.54 | ... | - | - | - | - | - | - | - | - | - | - |
| 466 | 42 | Pennsylvania | 133 | York County | 2005 | 408.801 | 41.850 | 257.985 | 299.835 | 3.18 | ... | - | - | - | - | - | - | - | - | - | - |
| 467 | 42 | Pennsylvania | 133 | York County | 2010 | 434.972 | 62.600 | 218.230 | 280.830 | 4.46 | ... | - | - | - | - | - | - | - | - | - | - |
| 468 | 42 | Pennsylvania | 133 | York County | 2015 | 442.867 | 59.710 | 219.304 | 279.014 | 3.56 | ... | - | - | - | - | - | - | - | - | - | - |
469 rows × 283 columns
Show the data types of the columns in the resulting data frame.
[5]:
print(pennsylvania[0].dtypes)
state_cd int64
state_name object
county_cd int64
county_nm object
year int64
...
Hydroelectric Power total number of facilities object
Wastewater Treatment returns by public wastewater facilities in Mgal/d object
Wastewater Treatment number of public wastewater facilities object
Wastewater Treatment number of wastewater facilities object
Wastewater Treatment reclaimed wastewater released by wastewater facilities in Mgal/d object
Length: 283, 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 264 water use records.
| state_cd | state_name | county_cd | county_nm | year | Total Population total population of area in thousands | Public Supply population served by groundwater in thousands | Public Supply population served by surface water in thousands | Public Supply total population served in thousands | Public Supply self-supplied groundwater withdrawals fresh in Mgal/d | ... | Hydroelectric Power power generated by instream use in gigawatt-hours | Hydroelectric Power power generated by offstream use in gigawatt-hours | Hydroelectric Power total power generated in gigawatt-hours | Hydroelectric Power number of instream facilities | Hydroelectric Power number of offstream facilities | Hydroelectric Power total number of facilities | Wastewater Treatment returns by public wastewater facilities in Mgal/d | Wastewater Treatment number of public wastewater facilities | Wastewater Treatment number of wastewater facilities | Wastewater Treatment reclaimed wastewater released by wastewater facilities in Mgal/d | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 39 | Ohio | 1 | Adams County | 2000 | 27.330 | 23.885 | 0.000 | 23.885 | 1.87 | ... | - | - | - | - | - | - | - | - | - | - |
| 1 | 39 | Ohio | 1 | Adams County | 2005 | 28.454 | 25.009 | 0.000 | 25.009 | 2.10 | ... | - | - | - | - | - | - | - | - | - | - |
| 2 | 39 | Ohio | 1 | Adams County | 2010 | 28.550 | 27.710 | 0.000 | 27.710 | 2.22 | ... | - | - | - | - | - | - | - | - | - | - |
| 3 | 39 | Ohio | 3 | Allen County | 2000 | 108.473 | 13.929 | 78.550 | 92.479 | 1.42 | ... | - | - | - | - | - | - | - | - | - | - |
| 4 | 39 | Ohio | 3 | Allen County | 2005 | 106.234 | 17.421 | 78.550 | 95.971 | 1.14 | ... | - | - | - | - | - | - | - | - | - | - |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 259 | 39 | Ohio | 173 | Wood County | 2005 | 123.929 | 5.726 | 73.596 | 79.322 | 0.36 | ... | - | - | - | - | - | - | - | - | - | - |
| 260 | 39 | Ohio | 173 | Wood County | 2010 | 125.488 | 6.738 | 77.336 | 84.074 | 0.34 | ... | - | - | - | - | - | - | - | - | - | - |
| 261 | 39 | Ohio | 175 | Wyandot County | 2000 | 22.908 | 5.499 | 6.600 | 12.099 | 0.71 | ... | - | - | - | - | - | - | - | - | - | - |
| 262 | 39 | Ohio | 175 | Wyandot County | 2005 | 22.813 | 5.629 | 6.600 | 12.229 | 0.73 | ... | - | - | - | - | - | - | - | - | - | - |
| 263 | 39 | Ohio | 175 | Wyandot County | 2010 | 22.615 | 5.629 | 6.600 | 12.229 | 0.60 | ... | - | - | - | - | - | - | - | - | - | - |
264 rows × 283 columns
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 735 water use records.
| state_cd | state_name | county_cd | county_nm | year | Livestock self-supplied groundwater withdrawals fresh in Mgal/d | Livestock self-supplied surface-water withdrawals fresh in Mgal/d | Livestock total self-supplied withdrawals fresh in Mgal/d | Livestock consumptive use fresh in Mgal/d | Irrigation Total self-supplied groundwater withdrawals fresh in Mgal/d | ... | Irrigation Total total self-supplied withdrawals in Mgal/d | Irrigation Total consumptive use fresh in Mgal/d | Irrigation Total consumptive use saline in Mgal/d | Irrigation Total total consumptive use in Mgal/d | Irrigation Total conveyance loss in Mgal/d | Irrigation Total sprinkler irrigation in thousand acres | Irrigation Total microirrigation in thousand acres | Irrigation Total surface irrigation in thousand acres | Irrigation Total total irrigation in thousand acres | Irrigation Total reclaimed wastewater in Mgal/d | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 20 | Kansas | 1 | Allen County | 1985 | - | - | - | - | 0.00 | ... | - | 1.26 | - | - | 0.10 | 0.20 | - | 1.00 | - | 0.00 |
| 1 | 20 | Kansas | 1 | Allen County | 1990 | - | - | - | - | 0.00 | ... | - | 0.17 | - | - | 0.01 | 0.00 | - | 0.78 | - | 0.00 |
| 2 | 20 | Kansas | 1 | Allen County | 1995 | - | - | - | - | 0.00 | ... | 0.03 | 0.03 | 0.00 | 0.03 | 0.00 | 0.16 | 0.00 | 0.00 | 0.16 | 0.00 |
| 3 | 20 | Kansas | 1 | Allen County | 2000 | 0.00 | 0.49 | 0.49 | - | 0.00 | ... | 0.26 | - | - | - | - | 0.43 | 0.00 | 0.00 | 0.43 | - |
| 4 | 20 | Kansas | 1 | Allen County | 2005 | 0.00 | 0.56 | 0.56 | - | 0.00 | ... | 0.08 | - | - | - | - | 0.56 | 0.00 | 0.00 | 0.56 | - |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 730 | 20 | Kansas | 209 | Wyandotte County | 1995 | - | - | - | - | 0.00 | ... | 0.10 | 0.10 | 0.00 | 0.10 | 0.00 | 0.07 | 0.00 | 0.00 | 0.07 | 0.00 |
| 731 | 20 | Kansas | 209 | Wyandotte County | 2000 | 0.00 | 0.05 | 0.05 | - | 0.10 | ... | 0.27 | - | - | - | - | 0.24 | 0.00 | 0.00 | 0.24 | - |
| 732 | 20 | Kansas | 209 | Wyandotte County | 2005 | 0.00 | 0.03 | 0.03 | - | 0.15 | ... | 0.39 | - | - | - | - | 0.60 | 0.00 | 0.00 | 0.60 | - |
| 733 | 20 | Kansas | 209 | Wyandotte County | 2010 | 0.00 | 0.03 | 0.03 | - | 0.10 | ... | 0.26 | - | - | - | - | 0.62 | 0.00 | 0.00 | 0.62 | - |
| 734 | 20 | Kansas | 209 | Wyandotte County | 2015 | 0.00 | 0.02 | 0.02 | - | 0.13 | ... | 0.26 | 0.17 | - | 0.17 | - | 0.82 | 0.00 | 0.09 | 0.91 | 0.00 |
735 rows × 27 columns