USGS dataretrieval Python Package get_discharge_peaks() Examples

This notebook provides examples of using the Python dataretrieval package to retrieve streamflow peak data for United States Geological Survey (USGS) monitoring sites. 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.

!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.

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_discharge_peaks() function to retrieve peak streamflow data for a USGS monitoring site from NWIS. The function has the following arguments:

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

• sites (list of strings): A list of USGS site identifiers for which data will be retrieved. If the waterdata parameter site_no is supplied, it will overwrite the sites parameter.

• start (string): A beginning date for the period for which data will be retrieved. If the waterdata parameter begin_date is supplied, it will overwrite the start parameter.

• end (string): An ending date for the period for which data will be retrieved. If the waterdata parameter end_date is supplied, it will overwrite the end parameter.

Example 1: Retrieve streamflow peak data for two USGS monitoring sites

site_ids = ["01594440", "040851325"]
peak_data = nwis.get_discharge_peaks(site_ids)
print("Retrieved " + str(len(peak_data[0])) + " data values.")

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[3], line 2
      1 site_ids = ["01594440", "040851325"]
----> 2 peak_data = nwis.get_discharge_peaks(site_ids)
      3 print("Retrieved " + str(len(peak_data[0])) + " data values.")

NameError: name 'nwis' is not defined

Interpreting the Result

The result of calling the get_discharge_peaks() function is an object that contains a Pandas data frame object and an associated metadata object. The Pandas data frame contains the discharge peak values for the requested site(s).

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.

display(peak_data[0])

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

NameError: name 'peak_data' is not defined

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

print(peak_data[0].dtypes)

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

NameError: name 'peak_data' is not defined

The other part of the result returned from the get_dv() 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.

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

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[6], line 1
----> 1 print("The query URL used to retrieve the data from NWIS was: " + peak_data[1].url)

NameError: name 'peak_data' is not defined

The following example is the same as the previous example but with multi index turned off (multi_index=False)

site_ids = ["01594440", "040851325"]
peak_data = nwis.get_discharge_peaks(site_ids, multi_index=False)
print("Retrieved " + str(len(peak_data[0])) + " data values.")

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[7], line 2
      1 site_ids = ["01594440", "040851325"]
----> 2 peak_data = nwis.get_discharge_peaks(site_ids, multi_index=False)
      3 print("Retrieved " + str(len(peak_data[0])) + " data values.")

NameError: name 'nwis' is not defined

Additional Examples

Example 2: Retrieve discharge peaks for a single site.

stations = "06011000"
data3 = nwis.get_discharge_peaks(stations)
display(data3[0])

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[8], line 2
      1 stations = "06011000"
----> 2 data3 = nwis.get_discharge_peaks(stations)
      3 display(data3[0])

NameError: name 'nwis' is not defined

Example 3: Retrieve peak discharge data for a monitoring site between two dates

data4 = nwis.get_discharge_peaks(stations, start="1953-01-01", end="1960-01-01")
display(data4[0])

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[9], line 1
----> 1 data4 = nwis.get_discharge_peaks(stations, start="1953-01-01", end="1960-01-01")
      2 display(data4[0])

NameError: name 'nwis' is not defined