USGS dataretrieval Python Package `get_discharge_measurements()` Examples

This notebook provides examples of using the Python dataretrieval package to retrieve surface water discharge measurement data for a United States Geological Survey (USGS) monitoring site. 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+g4dc9f6a68)
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.2)
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_discharge_measurements() function to retrieve surface water discharge measurements for a USGS monitoring site from NWIS. The function has the following arguments:

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

sites (list of strings): A list of USGS site codes to retrieve data for. If the qwdata parameter site_no is supplied, it will overwrite the sites parameter.
start (string): The beginning date of a period for which to retrieve measurements. If the qwdata parameter begin_date is supplied, it will overwrite the start parameter.
end (string): The ending date of a period for which to retrieve measurements. If the qwdata parameter end_date is supplied, it will overwrite the end parameter.

Example 1: Get all of the surface water measurements for a single site

[3]:

measurements1 = nwis.get_discharge_measurements(sites="10109000")
print("Retrieved " + str(len(measurements1[0])) + " data values.")

Retrieved 576 data values.

Interpreting the Result

The result of calling the get_discharge_measurements() function is an object that contains a Pandas data frame object and an associated metadata object. The Pandas data frame contains the discharge measurements for the time period requested.

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

[4]:

display(measurements1[0])

	<!DOCTYPE html>
0	<head>
1	<meta http-equiv="Content-Type" conten...
2	<meta http-equiv="X-UA-Compatible" con...
3	<meta name="viewport" content="width=d...
4	<meta name="format-detection" content=...
...	...
571	</div>
572	</div>
573	<script type="module" crossorigin="" src="...
574	</body>
575	</html>

576 rows × 1 columns

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

[5]:

print(measurements1[0].dtypes)

<!DOCTYPE html>    object
dtype: object

The other part of the result returned from the get_discharge_measurements() 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 USGS web service. The USGS web service responses contain a descriptive header that defines and can be helpful in interpreting the contents of the response.

[6]:

print("The query URL used to retrieve the data from NWIS was: " + measurements1[1].url)

The query URL used to retrieve the data from NWIS was: https://waterdata.usgs.gov/monitoring-location/USGS-10109000/

Additional Examples

Example 2: Get all of the surface water measurements between a start and end date

[7]:

measurements2 = nwis.get_discharge_measurements(sites="10109000", start="2019-01-01", end="2019-12-31")
print("Retrieved " + str(len(measurements2[0])) + " data values.")
display(measurements2[0])

Retrieved 576 data values.

	<!DOCTYPE html>
0	<head>
1	<meta http-equiv="Content-Type" conten...
2	<meta http-equiv="X-UA-Compatible" con...
3	<meta name="viewport" content="width=d...
4	<meta name="format-detection" content=...
...	...
571	</div>
572	</div>
573	<script type="module" crossorigin="" src="...
574	</body>
575	</html>