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.
[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_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
[3]:
site_ids = ['01594440', '040851325']
peak_data = nwis.get_discharge_peaks(site_ids)
print("Retrieved " + str(len(peak_data[0])) + " data values.")
Retrieved 55 data values.
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.
[4]:
display(peak_data[0])
| agency_cd | peak_tm | peak_va | peak_cd | gage_ht | gage_ht_cd | year_last_pk | ag_dt | ag_tm | ag_gage_ht | ag_gage_ht_cd | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| site_no | datetime | |||||||||||
| 01594440 | 1972-06-22 00:00:00+00:00 | USGS | NaN | 31100 | 5,7 | 27.90 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1978-01-27 00:00:00+00:00 | USGS | NaN | 10600 | 5 | 18.04 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1979-09-07 00:00:00+00:00 | USGS | NaN | 11500 | 5 | 18.52 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1979-10-11 00:00:00+00:00 | USGS | NaN | 3940 | 5 | 12.06 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1981-02-24 00:00:00+00:00 | USGS | NaN | 1640 | 5 | 9.60 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1982-02-04 00:00:00+00:00 | USGS | NaN | 3380 | 5 | 11.53 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1983-06-21 00:00:00+00:00 | USGS | NaN | 5750 | 5 | 14.28 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1984-03-30 00:00:00+00:00 | USGS | NaN | 4340 | 5 | 12.58 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1985-02-13 00:00:00+00:00 | USGS | NaN | 4730 | 5 | 13.07 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1986-04-16 00:00:00+00:00 | USGS | NaN | 1520 | 5 | 9.43 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1986-12-25 00:00:00+00:00 | USGS | NaN | 4060 | 5 | 12.21 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1987-11-30 00:00:00+00:00 | USGS | NaN | 3510 | 5 | 11.65 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1989-05-07 00:00:00+00:00 | USGS | NaN | 9190 | 5 | 16.84 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1990-05-30 00:00:00+00:00 | USGS | NaN | 3140 | 5 | 11.44 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1991-03-24 00:00:00+00:00 | USGS | NaN | 4750 | 5 | 12.95 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1992-03-27 00:00:00+00:00 | USGS | NaN | 3200 | 5 | 11.50 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1993-03-05 00:00:00+00:00 | USGS | NaN | 5550 | 5 | 13.76 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1993-11-29 00:00:00+00:00 | USGS | NaN | 6960 | 5 | 15.05 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1995-03-09 00:00:00+00:00 | USGS | NaN | 4100 | 5 | 12.32 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1996-01-20 00:00:00+00:00 | USGS | NaN | 8280 | 5 | 16.14 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1996-11-09 00:00:00+00:00 | USGS | NaN | 6900 | 5 | 15.00 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1998-03-10 00:00:00+00:00 | USGS | NaN | 4840 | 5 | 13.04 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 1999-09-17 00:00:00+00:00 | USGS | NaN | 8200 | 5 | 16.07 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2000-03-22 00:00:00+00:00 | USGS | NaN | 3640 | 5 | 11.90 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2001-06-08 00:00:00+00:00 | USGS | 06:30 | 3800 | 5 | 12.05 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2002-04-29 00:00:00+00:00 | USGS | NaN | 1510 | 2,5,8 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2003-02-23 00:00:00+00:00 | USGS | 19:30 | 6990 | 5 | 15.08 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2003-12-12 00:00:00+00:00 | USGS | 10:45 | 5790 | 5 | 13.99 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2005-04-03 00:00:00+00:00 | USGS | 19:15 | 5210 | 5 | 13.42 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2006-06-26 00:00:00+00:00 | USGS | 23:00 | 12700 | 5 | 19.20 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2007-04-16 00:00:00+00:00 | USGS | 11:15 | 5520 | 5 | 13.73 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2008-05-13 00:00:00+00:00 | USGS | 02:00 | 7860 | 5 | 15.80 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2009-06-19 00:00:00+00:00 | USGS | 05:45 | 4130 | 5 | 12.35 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2010-03-14 00:00:00+00:00 | USGS | 13:00 | 5780 | 5 | 13.98 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2011-09-08 00:00:00+00:00 | USGS | 13:15 | 16800 | 5 | 21.10 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2011-12-08 00:00:00+00:00 | USGS | 20:30 | 4900 | 5 | 13.74 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2012-10-30 00:00:00+00:00 | USGS | 23:00 | 10800 | 5 | 18.02 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2014-05-01 00:00:00+00:00 | USGS | 17:30 | 15600 | 5 | 20.56 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2015-06-28 00:00:00+00:00 | USGS | 18:15 | 6610 | 5 | 15.03 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2016-08-01 00:00:00+00:00 | USGS | 00:30 | 6140 | 5 | 14.64 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2017-07-30 00:00:00+00:00 | USGS | 01:15 | 4960 | 5 | 13.60 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2018-06-04 00:00:00+00:00 | USGS | 18:30 | 8360 | 5 | 16.32 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2018-12-16 00:00:00+00:00 | USGS | 23:30 | 7220 | 5 | 15.50 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2020-04-14 00:00:00+00:00 | USGS | 09:15 | 4340 | 5 | 12.99 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2020-11-12 00:00:00+00:00 | USGS | 17:45 | 4000 | 5 | 13.24 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2021-10-30 00:00:00+00:00 | USGS | 17:45 | 4590 | 5 | 13.74 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2022-12-16 00:00:00+00:00 | USGS | 14:15 | 3330 | 5 | 12.65 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 040851325 | 2005-08-18 00:00:00+00:00 | USGS | NaN | 267 | NaN | 4.30 | NaN | NaN | NaN | NaN | NaN | NaN |
| 2006-03-13 00:00:00+00:00 | USGS | NaN | 288 | NaN | 4.37 | 2.0 | NaN | 2006-05-12 | NaN | 4.45 | 1.0 | |
| 2007-03-14 00:00:00+00:00 | USGS | NaN | 301 | NaN | 4.58 | 2.0 | NaN | 2007-03-12 | NaN | 5.24 | 1.0 | |
| 2010-03-14 00:00:00+00:00 | USGS | NaN | 386 | NaN | 4.87 | 2.0 | NaN | 2010-03-13 | NaN | 5.22 | 1.0 | |
| 2011-03-18 00:00:00+00:00 | USGS | NaN | 436 | NaN | 5.02 | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2012-03-09 00:00:00+00:00 | USGS | NaN | 150 | NaN | 3.89 | 5.0 | NaN | NaN | NaN | NaN | NaN | |
| 2013-03-31 00:00:00+00:00 | USGS | NaN | 409 | NaN | 4.91 | 2.0 | NaN | 2013-03-13 | NaN | 5.42 | 1.0 | |
| 2014-06-02 00:00:00+00:00 | USGS | NaN | 429 | NaN | 5.00 | NaN | NaN | NaN | NaN | NaN | NaN |
Show the data types of the columns in the resulting data frame.
[5]:
print(peak_data[0].dtypes)
agency_cd object
peak_tm object
peak_va int64
peak_cd object
gage_ht float64
gage_ht_cd float64
year_last_pk float64
ag_dt object
ag_tm float64
ag_gage_ht float64
ag_gage_ht_cd float64
dtype: object
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.
[6]:
print("The query URL used to retrieve the data from NWIS was: " + peak_data[1].url)
The query URL used to retrieve the data from NWIS was: https://nwis.waterdata.usgs.gov/nwis/peaks?format=rdb&site_no=01594440%2C040851325
The following example is the same as the previous example but with multi index turned off (multi_index=False)
[7]:
site_ids = ['01594440', '040851325']
peak_data = nwis.get_discharge_peaks(site_ids, multi_index=False)
print("Retrieved " + str(len(peak_data[0])) + " data values.")
Retrieved 55 data values.
Additional Examples
Example 2: Retrieve discharge peaks for a single site.
[8]:
stations = "06011000"
data3 = nwis.get_discharge_peaks(stations)
display(data3[0])
| agency_cd | site_no | peak_tm | peak_va | peak_cd | gage_ht | gage_ht_cd | year_last_pk | ag_dt | ag_tm | ag_gage_ht | ag_gage_ht_cd | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| datetime | ||||||||||||
| 1937-04-28 00:00:00+00:00 | USGS | 06011000 | NaN | 964 | NaN | 3.52 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1938-04-27 00:00:00+00:00 | USGS | 06011000 | NaN | 1030 | NaN | 3.92 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1939-04-19 00:00:00+00:00 | USGS | 06011000 | NaN | 829 | NaN | 3.56 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1940-04-14 00:00:00+00:00 | USGS | 06011000 | NaN | 590 | NaN | 3.00 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1941-04-11 00:00:00+00:00 | USGS | 06011000 | NaN | 430 | NaN | 2.59 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1942-04-12 00:00:00+00:00 | USGS | 06011000 | NaN | 883 | NaN | 3.67 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1945-05-04 00:00:00+00:00 | USGS | 06011000 | NaN | 681 | NaN | 3.99 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1946-04-21 00:00:00+00:00 | USGS | 06011000 | NaN | 961 | NaN | 4.75 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1947-05-02 00:00:00+00:00 | USGS | 06011000 | NaN | 781 | NaN | 4.28 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1948-04-30 00:00:00+00:00 | USGS | 06011000 | NaN | 820 | NaN | 4.41 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1949-04-27 00:00:00+00:00 | USGS | 06011000 | NaN | 726 | NaN | 4.14 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1950-04-22 00:00:00+00:00 | USGS | 06011000 | NaN | 781 | NaN | 4.30 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1951-04-23 00:00:00+00:00 | USGS | 06011000 | NaN | 640 | NaN | 3.96 | 2 | NaN | 1951-04-15 | NaN | 4.47 | 1.0 |
| 1952-04-30 00:00:00+00:00 | USGS | 06011000 | NaN | 1360 | NaN | 5.24 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1953-05-05 00:00:00+00:00 | USGS | 06011000 | NaN | 715 | NaN | 4.10 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1954-04-23 00:00:00+00:00 | USGS | 06011000 | NaN | 546 | NaN | 3.54 | 2 | NaN | 1954-04-19 | NaN | 5.41 | NaN |
| 1956-04-24 00:00:00+00:00 | USGS | 06011000 | NaN | 596 | NaN | 3.77 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1957-05-06 00:00:00+00:00 | USGS | 06011000 | NaN | 1020 | NaN | 4.77 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1958-04-30 00:00:00+00:00 | USGS | 06011000 | NaN | 590 | NaN | 3.77 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1959-04-22 00:00:00+00:00 | USGS | 06011000 | NaN | 352 | NaN | 2.81 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1960-04-08 00:00:00+00:00 | USGS | 06011000 | NaN | 800 | 1 | NaN | NaN | NaN | 1960-04-08 | 1200.0 | 4.52 | 1.0 |
| 1961-04-05 00:00:00+00:00 | USGS | 06011000 | NaN | 300 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 1962-04-27 00:00:00+00:00 | USGS | 06011000 | NaN | 900 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 1963-04-20 00:00:00+00:00 | USGS | 06011000 | NaN | 486 | NaN | 3.20 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1964-04-28 00:00:00+00:00 | USGS | 06011000 | NaN | 751 | NaN | 4.20 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1965-04-28 00:00:00+00:00 | USGS | 06011000 | NaN | 958 | NaN | 4.66 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1966-04-16 00:00:00+00:00 | USGS | 06011000 | NaN | 524 | NaN | 3.28 | 2 | NaN | 1966-04-21 | NaN | 3.76 | 1.0 |
| 1967-05-12 00:00:00+00:00 | USGS | 06011000 | NaN | 604 | NaN | 3.75 | 2 | NaN | 1967-04-27 | NaN | 4.20 | 1.0 |
Example 3: Retrieve peak discharge data for a monitoring site between two dates
[9]:
data4 = nwis.get_discharge_peaks(stations, start='1953-01-01', end='1960-01-01')
display(data4[0])
| agency_cd | site_no | peak_tm | peak_va | peak_cd | gage_ht | gage_ht_cd | year_last_pk | ag_dt | ag_tm | ag_gage_ht | ag_gage_ht_cd | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| datetime | ||||||||||||
| 1953-05-05 00:00:00+00:00 | USGS | 06011000 | NaN | 715 | NaN | 4.10 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1954-04-23 00:00:00+00:00 | USGS | 06011000 | NaN | 546 | NaN | 3.54 | 2.0 | NaN | 1954-04-19 | NaN | 5.41 | NaN |
| 1956-04-24 00:00:00+00:00 | USGS | 06011000 | NaN | 596 | NaN | 3.77 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1957-05-06 00:00:00+00:00 | USGS | 06011000 | NaN | 1020 | NaN | 4.77 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1958-04-30 00:00:00+00:00 | USGS | 06011000 | NaN | 590 | NaN | 3.77 | NaN | NaN | NaN | NaN | NaN | NaN |
| 1959-04-22 00:00:00+00:00 | USGS | 06011000 | NaN | 352 | NaN | 2.81 | NaN | NaN | NaN | NaN | NaN | NaN |