USGS dataretrieval Python Package Peak Streamflow Examples
This notebook provides examples of using the Python dataretrieval package to retrieve annual peak streamflow data for United States Geological Survey (USGS) monitoring locations using the USGS Water Data API via the waterdata module. The waterdata module is the recommended way to access USGS water data and replaces the deprecated nwis module.
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
Requirement already satisfied: dataretrieval in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (0.1.dev1+gdff162cbd)
Requirement already satisfied: httpx in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from dataretrieval) (0.28.1)
Requirement already satisfied: pandas<4.0.0,>=2.0.0 in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from dataretrieval) (3.0.3)
Requirement already satisfied: numpy>=1.26.0 in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from pandas<4.0.0,>=2.0.0->dataretrieval) (2.4.6)
Requirement already satisfied: python-dateutil>=2.8.2 in /opt/hostedtoolcache/Python/3.13.13/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.13/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: anyio in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (4.13.0)
Requirement already satisfied: certifi in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (2026.5.20)
Requirement already satisfied: httpcore==1.* in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (1.0.9)
Requirement already satisfied: idna in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (3.18)
Requirement already satisfied: h11>=0.16 in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpcore==1.*->httpx->dataretrieval) (0.16.0)
Load the package so you can use it along with other packages used in this notebook.
[2]:
from IPython.display import display
from dataretrieval import waterdata
Basic Usage
This example uses the get_peaks() function to retrieve annual peak data for a USGS monitoring location. Commonly used arguments include:
monitoring_location_id (string or list of strings): USGS monitoring location id(s), formed as the agency code and site number joined by a hyphen (e.g.
"USGS-01594440").parameter_code (string or list of strings): 5-digit USGS parameter code(s). Peak records include both peak discharge (
00060) and the corresponding gage height (00065); passparameter_code="00060"to retrieve peak discharge only.time (string): an ISO-8601 date or interval (e.g.
"1953-01-01/1960-01-01") restricting the period retrieved.
Example 1: Retrieve peak discharge for two USGS monitoring locations
[3]:
site_ids = ["USGS-01594440", "USGS-040851325"]
peak_data = waterdata.get_peaks(
monitoring_location_id=site_ids, parameter_code="00060"
)
print("Retrieved " + str(len(peak_data[0])) + " peak values.")
Retrieving: peaks · 1 page · 57 rows
No API key detected — register for higher rate limits at https://api.waterdata.usgs.gov/signup/
Retrieved 57 peak values.
Interpreting the Result
Each waterdata function returns a tuple of a pandas data frame and a metadata object. The data frame contains one row per annual peak, including the peak value, its time, and the water_year.
Once you’ve got the data frame, there are several useful things you can do to explore the data.
Display the data frame as a table.
[4]:
display(peak_data[0])
| geometry | time_series_id | monitoring_location_id | parameter_code | unit_of_measure | value | last_modified | time | water_year | year | month | day | time_of_day | peak_since | qualifier | peak_id | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 31100 | 2026-05-01 19:28:03.170712+00:00 | 1972-06-22 | 1972 | 1972 | 6 | 22 | NaN | None | [HISTORIC, UNKNOWNREGULATION] | 3ae666b2-6658-4cd5-b0d9-9435e327f30e |
| 1 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 10600 | 2026-05-01 19:28:03.170712+00:00 | 1978-01-27 | 1978 | 1978 | 1 | 27 | NaN | None | [UNKNOWNREGULATION] | c2058a02-3a57-4867-b1eb-973d552bfa54 |
| 2 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 11500 | 2026-05-01 19:28:03.170712+00:00 | 1979-09-07 | 1979 | 1979 | 9 | 7 | NaN | None | [UNKNOWNREGULATION] | 513931e9-5d25-499b-9433-2e1b23f6a4a1 |
| 3 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 3940 | 2026-05-01 19:28:03.170712+00:00 | 1979-10-11 | 1980 | 1979 | 10 | 11 | NaN | None | [UNKNOWNREGULATION] | 3c4e6c32-42f1-4515-b90c-3194394ac576 |
| 4 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 1640 | 2026-05-01 19:28:03.170712+00:00 | 1981-02-24 | 1981 | 1981 | 2 | 24 | NaN | None | [UNKNOWNREGULATION] | 5df555c2-e9f7-4deb-bac5-3467d4eecf5c |
| 5 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 3380 | 2026-05-01 19:28:03.170712+00:00 | 1982-02-04 | 1982 | 1982 | 2 | 4 | NaN | None | [UNKNOWNREGULATION] | 5efca373-025b-4980-89ce-b5dcaa6639d8 |
| 6 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 5750 | 2026-05-01 19:28:03.170712+00:00 | 1983-06-21 | 1983 | 1983 | 6 | 21 | NaN | None | [UNKNOWNREGULATION] | 1d58764d-52c4-4344-bd29-9ab8852d1d89 |
| 7 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 4340 | 2026-05-01 19:28:03.170712+00:00 | 1984-03-30 | 1984 | 1984 | 3 | 30 | NaN | None | [UNKNOWNREGULATION] | 65bedc17-bc1f-4412-897e-c9c7bc763552 |
| 8 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 4730 | 2026-05-01 19:28:03.170712+00:00 | 1985-02-13 | 1985 | 1985 | 2 | 13 | NaN | None | [UNKNOWNREGULATION] | 6bedc7e5-5cc8-450d-b5a1-50449b20fe22 |
| 9 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 1520 | 2026-05-01 19:28:03.170712+00:00 | 1986-04-16 | 1986 | 1986 | 4 | 16 | NaN | None | [UNKNOWNREGULATION] | 2b87d057-7c2b-4cb7-bf44-576545008979 |
| 10 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 4060 | 2026-05-01 19:28:03.170712+00:00 | 1986-12-25 | 1987 | 1986 | 12 | 25 | NaN | None | [UNKNOWNREGULATION] | bf952852-cee7-43bc-88c9-70b197c4e62e |
| 11 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 3510 | 2026-05-01 19:28:03.170712+00:00 | 1987-11-30 | 1988 | 1987 | 11 | 30 | NaN | None | [UNKNOWNREGULATION] | 867ee68a-f8ea-4f55-a2e1-5e9df0077fcd |
| 12 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 9190 | 2026-05-01 19:28:03.170712+00:00 | 1989-05-07 | 1989 | 1989 | 5 | 7 | NaN | None | [UNKNOWNREGULATION] | 10718b58-5763-44e5-a044-812c677f0b61 |
| 13 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 3140 | 2026-05-01 19:28:03.170712+00:00 | 1990-05-30 | 1990 | 1990 | 5 | 30 | NaN | None | [UNKNOWNREGULATION] | 3dc8ee6a-c076-43d4-977a-e7252a94cac7 |
| 14 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 4750 | 2026-05-01 19:28:03.170712+00:00 | 1991-03-24 | 1991 | 1991 | 3 | 24 | NaN | None | [UNKNOWNREGULATION] | b9294137-2fad-4074-bd86-cf52f727ede6 |
| 15 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 3200 | 2026-05-01 19:28:03.170712+00:00 | 1992-03-27 | 1992 | 1992 | 3 | 27 | NaN | None | [UNKNOWNREGULATION] | 537bb753-c6d6-49a1-a4dc-2b16b29256b5 |
| 16 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 5550 | 2026-05-01 19:28:03.170712+00:00 | 1993-03-05 | 1993 | 1993 | 3 | 5 | NaN | None | [UNKNOWNREGULATION] | dddd1dbe-b92a-4739-84b8-350918ecdd7c |
| 17 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 6960 | 2026-05-01 19:28:03.170712+00:00 | 1993-11-29 | 1994 | 1993 | 11 | 29 | NaN | None | [UNKNOWNREGULATION] | 29e958a5-ebdb-4290-8fd8-843019b62155 |
| 18 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 4100 | 2026-05-01 19:28:03.170712+00:00 | 1995-03-09 | 1995 | 1995 | 3 | 9 | NaN | None | [UNKNOWNREGULATION] | 942af9b6-7ace-4d6a-8cb2-f359e9511af3 |
| 19 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 8280 | 2026-05-01 19:28:03.170712+00:00 | 1996-01-20 | 1996 | 1996 | 1 | 20 | NaN | None | [UNKNOWNREGULATION] | 09d0f0e1-c7ac-4136-b4f8-e4639b313386 |
| 20 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 6900 | 2026-05-01 19:28:03.170712+00:00 | 1996-11-09 | 1997 | 1996 | 11 | 9 | NaN | None | [UNKNOWNREGULATION] | 9abb8890-e9c6-45bb-a302-678dc691207e |
| 21 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 4840 | 2026-05-01 19:28:03.170712+00:00 | 1998-03-10 | 1998 | 1998 | 3 | 10 | NaN | None | [UNKNOWNREGULATION] | 01766a4b-dab4-4698-9c6a-3ef8f2e11153 |
| 22 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 8200 | 2026-05-01 19:28:03.170712+00:00 | 1999-09-17 | 1999 | 1999 | 9 | 17 | NaN | None | [UNKNOWNREGULATION] | 9e4dd73c-afd1-4fd2-95f4-3f5b3af886c4 |
| 23 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 3640 | 2026-05-01 19:28:03.170712+00:00 | 2000-03-22 | 2000 | 2000 | 3 | 22 | NaN | None | [UNKNOWNREGULATION] | 01ad0ff4-f40e-4ad1-93e4-9460f5de1353 |
| 24 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 3800 | 2026-05-01 19:28:03.170712+00:00 | 2001-06-08 | 2001 | 2001 | 6 | 8 | 10:30:00+00:00 | None | [UNKNOWNREGULATION] | 3ea2d208-4285-4b9a-adeb-9b17b0d67fea |
| 25 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 1510 | 2026-05-01 19:28:03.170712+00:00 | 2002-04-29 | 2002 | 2002 | 4 | 29 | NaN | None | [ESTIMATED, GREATERTHAN, UNKNOWNREGULATION] | 9ad09dcd-0e49-4baf-a5dd-cb3b1dfb4c1a |
| 26 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 6990 | 2026-05-01 19:28:03.170712+00:00 | 2003-02-24 | 2003 | 2003 | 2 | 24 | 00:30:00+00:00 | None | [UNKNOWNREGULATION] | 406312f8-f7ff-4e68-ade4-8b4dd426bd44 |
| 27 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 5790 | 2026-05-01 19:28:03.170712+00:00 | 2003-12-12 | 2004 | 2003 | 12 | 12 | 15:45:00+00:00 | None | [UNKNOWNREGULATION] | e4550eba-d130-48e4-9abe-f7077b130ee8 |
| 28 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 5210 | 2026-05-01 19:28:03.170712+00:00 | 2005-04-03 | 2005 | 2005 | 4 | 3 | 23:15:00+00:00 | None | [UNKNOWNREGULATION] | c06f6cf2-8668-4f70-851a-b8d704a24807 |
| 29 | POINT (-87.93621 44.5011) | fdd843797b3246efb9f4aa344b5946cc | USGS-040851325 | 00060 | ft^3/s | 267 | 2026-05-05 03:36:50.236554+00:00 | 2005-08-18 | 2005 | 2005 | 8 | 18 | NaN | None | None | 90bfb29a-82c2-4bba-85cb-f58b87874e28 |
| 30 | POINT (-87.93621 44.5011) | fdd843797b3246efb9f4aa344b5946cc | USGS-040851325 | 00060 | ft^3/s | 288 | 2026-05-05 03:36:50.236554+00:00 | 2006-03-13 | 2006 | 2006 | 3 | 13 | NaN | None | None | b94cec80-5c1a-4c93-ad21-a6eea949ab67 |
| 31 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 12700 | 2026-05-01 19:28:03.170712+00:00 | 2006-06-27 | 2006 | 2006 | 6 | 27 | 03:00:00+00:00 | None | [UNKNOWNREGULATION] | b5fc68ad-d404-412a-8bdf-5df5c135887f |
| 32 | POINT (-87.93621 44.5011) | fdd843797b3246efb9f4aa344b5946cc | USGS-040851325 | 00060 | ft^3/s | 301 | 2026-05-05 03:36:50.236554+00:00 | 2007-03-14 | 2007 | 2007 | 3 | 14 | NaN | None | None | ce07ea88-b517-40a9-8a79-d45d0708c4ca |
| 33 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 5520 | 2026-05-01 19:28:03.170712+00:00 | 2007-04-16 | 2007 | 2007 | 4 | 16 | 15:15:00+00:00 | None | [UNKNOWNREGULATION] | 33973c47-235c-49a6-ad3f-d4ae6dbbe64e |
| 34 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 7860 | 2026-05-01 19:28:03.170712+00:00 | 2008-05-13 | 2008 | 2008 | 5 | 13 | 06:00:00+00:00 | None | [UNKNOWNREGULATION] | c64dc6a7-4a8d-414a-9eae-fbbb9f5faf93 |
| 35 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 4130 | 2026-05-01 19:28:03.170712+00:00 | 2009-06-19 | 2009 | 2009 | 6 | 19 | 09:45:00+00:00 | None | [UNKNOWNREGULATION] | 6d756602-b9e4-4063-ad59-870b56014f4d |
| 36 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 5780 | 2026-05-01 19:28:03.170712+00:00 | 2010-03-14 | 2010 | 2010 | 3 | 14 | 17:00:00+00:00 | None | [UNKNOWNREGULATION] | 29ffbe23-6ed6-4c4a-97be-062acb4a4877 |
| 37 | POINT (-87.93621 44.5011) | fdd843797b3246efb9f4aa344b5946cc | USGS-040851325 | 00060 | ft^3/s | 386 | 2026-05-05 03:36:50.236554+00:00 | 2010-03-14 | 2010 | 2010 | 3 | 14 | NaN | None | None | c4324b2a-1ef8-4aed-b3f2-26fbbd57cb79 |
| 38 | POINT (-87.93621 44.5011) | fdd843797b3246efb9f4aa344b5946cc | USGS-040851325 | 00060 | ft^3/s | 436 | 2026-05-05 03:36:50.236554+00:00 | 2011-03-18 | 2011 | 2011 | 3 | 18 | NaN | None | None | 6074a5e7-4cb5-4177-98c4-66399fb74609 |
| 39 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 16800 | 2026-05-01 19:28:03.170712+00:00 | 2011-09-08 | 2011 | 2011 | 9 | 8 | 17:15:00+00:00 | None | [UNKNOWNREGULATION] | ba30e845-6905-41ec-af84-92804d870a0e |
| 40 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 4900 | 2026-05-01 19:28:03.170712+00:00 | 2011-12-09 | 2012 | 2011 | 12 | 9 | 01:30:00+00:00 | None | [UNKNOWNREGULATION] | 3b9cb606-0785-4d3e-9e52-3efa0ad559d9 |
| 41 | POINT (-87.93621 44.5011) | fdd843797b3246efb9f4aa344b5946cc | USGS-040851325 | 00060 | ft^3/s | 150 | 2026-05-05 03:36:50.236554+00:00 | 2012-03-09 | 2012 | 2012 | 3 | 9 | NaN | None | None | 3bc2c0c3-50d0-44fe-a640-32a8219364b1 |
| 42 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 10800 | 2026-05-01 19:28:03.170712+00:00 | 2012-10-31 | 2013 | 2012 | 10 | 31 | 03:00:00+00:00 | None | [UNKNOWNREGULATION] | 7a277bcb-435f-4b1e-b67c-dd5dac818ac2 |
| 43 | POINT (-87.93621 44.5011) | fdd843797b3246efb9f4aa344b5946cc | USGS-040851325 | 00060 | ft^3/s | 409 | 2026-05-05 03:36:50.236554+00:00 | 2013-03-31 | 2013 | 2013 | 3 | 31 | NaN | None | None | 9c628482-896d-4a8a-b12f-091b216cef52 |
| 44 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 15600 | 2026-05-01 19:28:03.170712+00:00 | 2014-05-01 | 2014 | 2014 | 5 | 1 | 21:30:00+00:00 | None | [UNKNOWNREGULATION] | c46e2dc3-6a5c-47ce-9322-dbf417d03caa |
| 45 | POINT (-87.93621 44.5011) | fdd843797b3246efb9f4aa344b5946cc | USGS-040851325 | 00060 | ft^3/s | 429 | 2026-05-05 03:36:50.236554+00:00 | 2014-06-02 | 2014 | 2014 | 6 | 2 | NaN | None | None | bd89314d-4ba6-429f-83fa-567e5f73ae25 |
| 46 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 6610 | 2026-05-01 19:28:03.170712+00:00 | 2015-06-28 | 2015 | 2015 | 6 | 28 | 22:15:00+00:00 | None | [UNKNOWNREGULATION] | 84722b5e-c286-4d69-bdf1-75e05665adb0 |
| 47 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 6140 | 2026-05-01 19:28:03.170712+00:00 | 2016-08-01 | 2016 | 2016 | 8 | 1 | 04:30:00+00:00 | None | [UNKNOWNREGULATION] | 6caf417c-10b1-450d-957f-e5d43973afa9 |
| 48 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 4960 | 2026-05-01 19:28:03.170712+00:00 | 2017-07-30 | 2017 | 2017 | 7 | 30 | 05:15:00+00:00 | None | [UNKNOWNREGULATION] | e7d3ffaa-e6ff-486e-bbd0-5fcbb11a6268 |
| 49 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 8360 | 2026-05-01 19:28:03.170712+00:00 | 2018-06-04 | 2018 | 2018 | 6 | 4 | 22:30:00+00:00 | None | [UNKNOWNREGULATION] | 99f75026-7ad8-4e9f-bec8-9da13af22530 |
| 50 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 7220 | 2026-05-01 19:28:03.170712+00:00 | 2018-12-17 | 2019 | 2018 | 12 | 17 | 04:30:00+00:00 | None | [UNKNOWNREGULATION] | f8b816ae-c4a4-4f99-aa80-470856f0c334 |
| 51 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 4340 | 2026-05-01 19:28:03.170712+00:00 | 2020-04-14 | 2020 | 2020 | 4 | 14 | 13:15:00+00:00 | None | [UNKNOWNREGULATION] | 6ce447e3-ec2a-47df-bc1a-71ceff4e47fc |
| 52 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 4000 | 2026-05-01 19:28:03.170712+00:00 | 2020-11-12 | 2021 | 2020 | 11 | 12 | 22:45:00+00:00 | None | [UNKNOWNREGULATION] | fd1f1fb2-0329-42ad-bdd1-866d46ef6461 |
| 53 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 4590 | 2026-05-01 19:28:03.170712+00:00 | 2021-10-30 | 2022 | 2021 | 10 | 30 | 21:45:00+00:00 | None | [UNKNOWNREGULATION] | d353f7b9-eba2-41a9-baa8-fd787e199b23 |
| 54 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 3330 | 2026-05-01 19:28:03.170712+00:00 | 2022-12-16 | 2023 | 2022 | 12 | 16 | 19:15:00+00:00 | None | [UNKNOWNREGULATION] | b68c3597-8210-4f49-8af6-05b14f003bb0 |
| 55 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 7400 | 2026-05-01 19:28:03.170712+00:00 | 2024-01-11 | 2024 | 2024 | 1 | 11 | 00:15:00+00:00 | None | [UNKNOWNREGULATION] | 850c52c4-5567-4e2f-b30a-fda4fcd0e121 |
| 56 | POINT (-76.69369 38.95592) | 92a4e13a755d406abad1529f6add68e9 | USGS-01594440 | 00060 | ft^3/s | 2320 | 2026-05-01 19:28:03.170712+00:00 | 2025-06-19 | 2025 | 2025 | 6 | 19 | 18:45:00+00:00 | None | [UNKNOWNREGULATION] | f9895515-e652-483e-97d2-70412cafa722 |
Show the data types of the columns in the resulting data frame.
[5]:
print(peak_data[0].dtypes)
geometry geometry
time_series_id str
monitoring_location_id str
parameter_code str
unit_of_measure str
value int64
last_modified datetime64[us, UTC]
time datetime64[us]
water_year int64
year int64
month int64
day int64
time_of_day str
peak_since object
qualifier object
peak_id str
dtype: object
The other part of the result is a metadata object describing the query that was executed. For example, you can access the URL that was assembled to retrieve the requested data from the USGS Water Data API.
[6]:
print("The query URL used to retrieve the data was: " + peak_data[1].url)
The query URL used to retrieve the data was: https://api.waterdata.usgs.gov/ogcapi/v0/collections/peaks/items?monitoring_location_id=USGS-01594440%2CUSGS-040851325¶meter_code=00060&skipGeometry=false&limit=50000
Peak records cover multiple parameters. By default get_peaks() returns both peak discharge (00060) and the gage height at the peak (00065); inspect the parameter_code column to see which are present.
[7]:
all_params = waterdata.get_peaks(monitoring_location_id="USGS-01594440")
print(all_params[0]["parameter_code"].unique())
Retrieving: peaks · 1 page · 97 rows
<StringArray>
['00060', '00065']
Length: 2, dtype: str
Additional Examples
Example 2: Retrieve peak discharge for a single monitoring location
[8]:
station = "USGS-06011000"
data3 = waterdata.get_peaks(monitoring_location_id=station, parameter_code="00060")
display(data3[0])
Retrieving: peaks · 1 page · 29 rows
| geometry | time_series_id | monitoring_location_id | parameter_code | unit_of_measure | value | last_modified | time | water_year | year | month | day | time_of_day | peak_since | qualifier | peak_id | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 964 | 2026-05-06 17:32:44.238660+00:00 | 1937-04-28 | 1937 | 1937 | 4 | 28.0 | None | None | None | 8489606e-89e2-4cab-9758-969be99c7efc |
| 1 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 1030 | 2026-05-06 17:32:44.238660+00:00 | 1938-04-27 | 1938 | 1938 | 4 | 27.0 | None | None | None | 2091dc02-2a41-4bd7-a38d-018aff41d2d3 |
| 2 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 829 | 2026-05-06 17:32:44.238660+00:00 | 1939-04-19 | 1939 | 1939 | 4 | 19.0 | None | None | None | 54d4673d-232b-4c0f-84ac-3f2cfa25eae6 |
| 3 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 590 | 2026-05-06 17:32:44.238660+00:00 | 1940-04-14 | 1940 | 1940 | 4 | 14.0 | None | None | None | d65a02cd-7e38-419e-9ca0-f82f7ffb66bb |
| 4 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 430 | 2026-05-06 17:32:44.238660+00:00 | 1941-04-11 | 1941 | 1941 | 4 | 11.0 | None | None | None | 873cdcce-0b39-4328-b5d2-279318692e40 |
| 5 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 883 | 2026-05-06 17:32:44.238660+00:00 | 1942-04-12 | 1942 | 1942 | 4 | 12.0 | None | None | None | 95dc6356-39c1-4a3b-b6e4-05f346366e70 |
| 6 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 681 | 2026-05-06 17:32:44.238660+00:00 | 1945-05-04 | 1945 | 1945 | 5 | 4.0 | None | None | None | 3889ccaf-cac9-40fd-8900-56ee32fad15f |
| 7 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 961 | 2026-05-06 17:32:44.238660+00:00 | 1946-04-21 | 1946 | 1946 | 4 | 21.0 | None | None | None | 13c36dc5-80ec-43b0-96f5-62a072a7d2d3 |
| 8 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 781 | 2026-05-06 17:32:44.238660+00:00 | 1947-05-02 | 1947 | 1947 | 5 | 2.0 | None | None | None | 57120111-fa2d-476e-bdf7-603cbfb03350 |
| 9 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 820 | 2026-05-06 17:32:44.238660+00:00 | 1948-04-30 | 1948 | 1948 | 4 | 30.0 | None | None | None | 8e99a440-8114-4ded-9d68-5a06f9d7c7ea |
| 10 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 726 | 2026-05-06 17:32:44.238660+00:00 | 1949-04-27 | 1949 | 1949 | 4 | 27.0 | None | None | None | 4de7db39-d552-4e44-9625-e80af36f552c |
| 11 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 781 | 2026-05-06 17:32:44.238660+00:00 | 1950-04-22 | 1950 | 1950 | 4 | 22.0 | None | None | None | f9a71afe-de67-497e-a6d4-9f660041f0db |
| 12 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 640 | 2026-05-06 17:32:44.238660+00:00 | 1951-04-23 | 1951 | 1951 | 4 | 23.0 | None | None | None | f2dac095-aeac-4999-bfb7-4092d1651536 |
| 13 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 1360 | 2026-05-06 17:32:44.238660+00:00 | 1952-04-30 | 1952 | 1952 | 4 | 30.0 | None | None | None | 42dfc367-59cf-4d12-ab62-405f856697ca |
| 14 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 715 | 2026-05-06 17:32:44.238660+00:00 | 1953-05-05 | 1953 | 1953 | 5 | 5.0 | None | None | None | c8c99d0a-1172-4ef4-adf4-892331793e1e |
| 15 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 546 | 2026-05-06 17:32:44.238660+00:00 | 1954-04-23 | 1954 | 1954 | 4 | 23.0 | None | None | None | dd627cb7-9bc0-43fc-a492-cbc38d0b48d7 |
| 16 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 596 | 2026-05-06 17:32:44.238660+00:00 | 1956-04-24 | 1956 | 1956 | 4 | 24.0 | None | None | None | c1e1d9c4-6ad8-4280-baf8-742511f5e9ef |
| 17 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 1020 | 2026-05-06 17:32:44.238660+00:00 | 1957-05-06 | 1957 | 1957 | 5 | 6.0 | None | None | None | d2f8e901-5fe4-41ca-944a-fb430e30b678 |
| 18 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 590 | 2026-05-06 17:32:44.238660+00:00 | 1958-04-30 | 1958 | 1958 | 4 | 30.0 | None | None | None | 8eb49b9a-dad1-4017-b07f-5a34b8918062 |
| 19 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 352 | 2026-05-06 17:32:44.238660+00:00 | 1959-04-22 | 1959 | 1959 | 4 | 22.0 | None | None | None | 184e855e-57e8-4521-a570-97d9e15e8973 |
| 20 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 800 | 2026-05-06 17:32:44.238660+00:00 | 1960-04-08 | 1960 | 1960 | 4 | 8.0 | None | None | [MAXDAILYMEAN] | 57371ba5-8341-4d3e-ac4a-3d6f74e2a515 |
| 21 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 300 | 2026-05-06 17:32:44.238660+00:00 | 1961-04-05 | 1961 | 1961 | 4 | 5.0 | None | None | None | 185789b2-59cd-42ff-b37f-f1fc734f85b3 |
| 22 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 900 | 2026-05-06 17:32:44.238660+00:00 | 1962-04-27 | 1962 | 1962 | 4 | 27.0 | None | None | None | 94025d15-a950-46ee-915e-15eb9e009819 |
| 23 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 486 | 2026-05-06 17:32:44.238660+00:00 | 1963-04-20 | 1963 | 1963 | 4 | 20.0 | None | None | None | 945a0c09-7b64-4f4b-91bc-cd1d83b3a248 |
| 24 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 751 | 2026-05-06 17:32:44.238660+00:00 | 1964-04-28 | 1964 | 1964 | 4 | 28.0 | None | None | None | 10ae014a-2a37-466a-aba4-78540e1fda47 |
| 25 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 958 | 2026-05-06 17:32:44.238660+00:00 | 1965-04-28 | 1965 | 1965 | 4 | 28.0 | None | None | None | 59a2fcb8-bed1-4ac8-8582-bb63fb9f9e11 |
| 26 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 524 | 2026-05-06 17:32:44.238660+00:00 | 1966-04-16 | 1966 | 1966 | 4 | 16.0 | None | None | None | 49ea8bac-0e8a-4bec-b981-49a69c925ca7 |
| 27 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 604 | 2026-05-06 17:32:44.238660+00:00 | 1967-05-12 | 1967 | 1967 | 5 | 12.0 | None | None | None | 6dee7073-0873-4765-91f1-ed8afb934620 |
| 28 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 1180 | 2026-05-06 17:32:44.238660+00:00 | 1984-05-01 | 1984 | 1984 | 5 | NaN | None | None | [DAYUNKNOWN, HISTORIC] | 21969473-a764-470b-8ec6-5fa316dbe362 |
Example 3: Retrieve peak discharge for a monitoring location between two dates
[9]:
data4 = waterdata.get_peaks(
monitoring_location_id=station,
parameter_code="00060",
time="1953-01-01/1960-01-01",
)
display(data4[0])
Retrieving: peaks · 1 page · 6 rows
| geometry | time_series_id | monitoring_location_id | parameter_code | unit_of_measure | value | last_modified | time | water_year | year | month | day | time_of_day | peak_since | qualifier | peak_id | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 715 | 2026-05-06 17:32:44.238660+00:00 | 1953-05-05 | 1953 | 1953 | 5 | 5 | None | None | None | c8c99d0a-1172-4ef4-adf4-892331793e1e |
| 1 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 546 | 2026-05-06 17:32:44.238660+00:00 | 1954-04-23 | 1954 | 1954 | 4 | 23 | None | None | None | dd627cb7-9bc0-43fc-a492-cbc38d0b48d7 |
| 2 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 596 | 2026-05-06 17:32:44.238660+00:00 | 1956-04-24 | 1956 | 1956 | 4 | 24 | None | None | None | c1e1d9c4-6ad8-4280-baf8-742511f5e9ef |
| 3 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 1020 | 2026-05-06 17:32:44.238660+00:00 | 1957-05-06 | 1957 | 1957 | 5 | 6 | None | None | None | d2f8e901-5fe4-41ca-944a-fb430e30b678 |
| 4 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 590 | 2026-05-06 17:32:44.238660+00:00 | 1958-04-30 | 1958 | 1958 | 4 | 30 | None | None | None | 8eb49b9a-dad1-4017-b07f-5a34b8918062 |
| 5 | POINT (-112.05641 44.64793) | 1803f93f789a46f093cc4e7695554bdb | USGS-06011000 | 00060 | ft^3/s | 352 | 2026-05-06 17:32:44.238660+00:00 | 1959-04-22 | 1959 | 1959 | 4 | 22 | None | None | None | 184e855e-57e8-4521-a570-97d9e15e8973 |