USGS dataretrieval Python Package get_monitoring_locations() Examples
This notebook provides examples of using the Python dataretrieval package to retrieve information about a United States Geological Survey (USGS) monitoring location. The dataretrieval package provides a collection of functions to get data from the USGS Water Data API and other online sources of hydrology and water quality data.
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+g7f64c2de7)
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.16)
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
import dataretrieval.waterdata as waterdata
Basic Usage
The dataretrieval package has several functions that allow you to retrieve data from the USGS Water Data API. This example uses the get_monitoring_locations() function to retrieve information about USGS monitoring locations. The function accepts many optional query arguments; supplying one or more of them filters the locations that are returned. The arguments used in the examples below are:
monitoring_location_id (string or iterable of strings): A unique identifier for a single monitoring location. A monitoring location id joins the code of the agency responsible for the location (e.g.
USGS) and the location’s id number (e.g.10109000) with a hyphen (e.g.USGS-10109000).state_code (string or iterable of strings): State code. A two-digit ANSI code (formerly FIPS code) as defined by the American National Standards Institute, used to define states and equivalents.
state_name (string or iterable of strings): The name of the state or state equivalent in which the monitoring location is located.
hydrologic_unit_code (string or iterable of strings): A hydrologic unit code (HUC) of two to eight digits identifying a hydrologic unit (region, sub-region, accounting unit, or cataloging unit). For example,
hydrologic_unit_code="16010203"selects locations within that cataloging unit.site_type_code (string or iterable of strings): A code describing the hydrologic setting of the monitoring location, such as stream, spring, or well. For example,
site_type_code="ST"returns streams only.skip_geometry (boolean): If
True, response geometries are skipped and the returned object is a plainpandas.DataFramewith no spatial information. Otherwise the result is ageopandas.GeoDataFramethat includes ageometrycolumn.
Many additional filter arguments are available, including monitoring_location_name, county_code, county_name, site_type, aquifer_code, bbox, and properties. For the complete list of arguments and their descriptions, see the get_monitoring_locations() docstring and the USGS Water Data API documentation.
Example 1: Get information for a USGS monitoring location
[3]:
# Specify the site you want to retrieve information for
siteID = "USGS-10109000"
# Get the site information
siteINFO = waterdata.get_monitoring_locations(monitoring_location_id=siteID)
Retrieving: monitoring-locations · 1 page · 1 rows
No API key detected — register for higher rate limits at https://api.waterdata.usgs.gov/signup/
Interpreting the Result
The get_monitoring_locations() function returns a tuple of two items: a pandas data frame (siteINFO[0]) and an associated metadata object (siteINFO[1]). The data frame contains one row per monitoring location, with a column for each location attribute. Unless skip_geometry=True is passed, the data frame is a geopandas.GeoDataFrame and includes a geometry column holding the location’s coordinates.
Once you have the data frame, there are several useful things you can do to explore the information about the location.
[4]:
# Display the data frame as a table
display(siteINFO[0])
| monitoring_location_id | geometry | agency_code | agency_name | monitoring_location_number | monitoring_location_name | district_code | country_code | country_name | state_code | ... | construction_date | aquifer_code | national_aquifer_code | aquifer_type_code | well_constructed_depth | hole_constructed_depth | depth_source_code | revision_note | revision_created | revision_modified | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | USGS-10109000 | POINT (-111.78398 41.74355) | USGS | U.S. Geological Survey | 10109000 | LOGAN RIVER ABOVE STATE DAM, NEAR LOGAN, UT | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | WDR UT-74-1: Drainage area. WDR UT-96-1:1995, ... | 2017-11-13T06:00:00+00:00 | None |
1 rows × 44 columns
Show the data types of the columns in the resulting data frame.
[5]:
print(siteINFO[0].dtypes)
monitoring_location_id str
geometry geometry
agency_code str
agency_name str
monitoring_location_number str
monitoring_location_name str
district_code str
country_code str
country_name str
state_code str
state_name str
county_code str
county_name str
minor_civil_division_code str
site_type_code str
site_type str
hydrologic_unit_code str
basin_code str
altitude float64
altitude_accuracy float64
altitude_method_code str
altitude_method_name str
vertical_datum str
vertical_datum_name str
horizontal_positional_accuracy_code str
horizontal_positional_accuracy str
horizontal_position_method_code str
horizontal_position_method_name str
original_horizontal_datum str
original_horizontal_datum_name str
drainage_area float64
contributing_drainage_area float64
time_zone_abbreviation str
uses_daylight_savings str
construction_date datetime64[s]
aquifer_code object
national_aquifer_code object
aquifer_type_code object
well_constructed_depth float64
hole_constructed_depth float64
depth_source_code object
revision_note str
revision_created str
revision_modified object
dtype: object
The other part of the result returned from the get_monitoring_locations() 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 Water Data API.
[6]:
print("The query URL used to retrieve the data from the Water Data API was: " + siteINFO[1].url)
The query URL used to retrieve the data from the Water Data API was: https://api.waterdata.usgs.gov/ogcapi/v0/collections/monitoring-locations/items?id=USGS-10109000&skipGeometry=false&limit=50000
Additional Examples
Example 2: Get information for multiple monitoring locations in a list
[7]:
# Create a list of the site identifiers you want to retrieve information for
siteIDs = ["USGS-05114000", "USGS-09423350"]
# Get the site information
siteINFO_multi = waterdata.get_monitoring_locations(monitoring_location_id=siteIDs)
display(siteINFO_multi[0])
Retrieving: monitoring-locations · 1 page · 2 rows
| monitoring_location_id | geometry | agency_code | agency_name | monitoring_location_number | monitoring_location_name | district_code | country_code | country_name | state_code | ... | construction_date | aquifer_code | national_aquifer_code | aquifer_type_code | well_constructed_depth | hole_constructed_depth | depth_source_code | revision_note | revision_created | revision_modified | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | USGS-05114000 | POINT (-101.95833 48.98996) | USGS | U.S. Geological Survey | 05114000 | SOURIS RIVER NEAR SHERWOOD, ND | 38 | US | United States of America | 38 | ... | NaT | None | None | None | NaN | NaN | None | WSP 1308: 1934, 1945. WSP 2113: Drainage area. | 2017-11-13T06:00:00+00:00 | NaN |
| 1 | USGS-09423350 | POINT (-115.29899 35.24501) | USGS | U.S. Geological Survey | 09423350 | CARUTHERS C NR IVANPAH CA | 06 | US | United States of America | 06 | ... | NaT | None | None | None | NaN | NaN | None | WDR CA-82-1: 1979 (instantaneous maximum disch... | 2017-11-13T06:00:00+00:00 | 2021-12-16T19:00:23.473000+00:00 |
2 rows × 44 columns
Example 3: Get information for all monitoring locations within a state
[8]:
# Get the site information for a state
siteINFO_state = waterdata.get_monitoring_locations(state_code="UT")
display(siteINFO_state[0])
Retrieving: monitoring-locations · 1 page
| geometry | monitoring_location_id | agency_code | agency_name | monitoring_location_number | monitoring_location_name | district_code | country_code | country_name | state_code | ... | construction_date | aquifer_code | national_aquifer_code | aquifer_type_code | well_constructed_depth | hole_constructed_depth | depth_source_code | revision_note | revision_created | revision_modified |
|---|
0 rows × 44 columns
Example 4: Get all “stream” monitoring locations within a USGS HUC
[9]:
# Create a list of hucs for which to query sites
huc_list = ["16010203"]
# Get the site information - limit to stream sites
siteINFO_huc = waterdata.get_monitoring_locations(hydrologic_unit_code=huc_list, site_type_code="ST")
display(siteINFO_huc[0])
Retrieving: monitoring-locations · 1 page · 29 rows
| monitoring_location_id | geometry | agency_code | agency_name | monitoring_location_number | monitoring_location_name | district_code | country_code | country_name | state_code | ... | construction_date | aquifer_code | national_aquifer_code | aquifer_type_code | well_constructed_depth | hole_constructed_depth | depth_source_code | revision_note | revision_created | revision_modified | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | USGS-10104600 | POINT (-111.81661 41.50021) | USGS | U.S. Geological Survey | 10104600 | SOUTH FORK LITTLE BEAR RIVER NEAR AVON, UTAH | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 1 | USGS-10104700 | POINT (-111.81189 41.51244) | USGS | U.S. Geological Survey | 10104700 | LITTLE BEAR R BL DAVENPORT C NR AVON UT | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 2 | USGS-10104900 | POINT (-111.71438 41.51827) | USGS | U.S. Geological Survey | 10104900 | EAST FK LT BEAR RIV AB RESV NR AVON UTAH | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 3 | USGS-10105000 | POINT (-111.75077 41.5166) | USGS | U.S. Geological Survey | 10105000 | EAST FORK LITTLE BEAR R NR AVON UTAH | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 4 | USGS-10105900 | POINT (-111.85522 41.57549) | USGS | U.S. Geological Survey | 10105900 | LITTLE BEAR RIVER AT PARADISE, UT | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 5 | USGS-10106000 | POINT (-111.85355 41.59021) | USGS | U.S. Geological Survey | 10106000 | LITTLE BEAR RIVER NEAR PARADISE, UTAH | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 6 | USGS-10107500 | POINT (-111.88411 41.63327) | USGS | U.S. Geological Survey | 10107500 | LITTLE BEAR RIVER NEAR HYRUM, UTAH | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 7 | USGS-10107600 | POINT (-111.92356 41.64743) | USGS | U.S. Geological Survey | 10107600 | LITTLE BEAR RIV AT WELLSVILLE UTAH | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 8 | USGS-10107700 | POINT (-111.56744 41.93326) | USGS | U.S. Geological Survey | 10107700 | LOGAN RIVER NR GARDEN CITY, UTAH | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 9 | USGS-10107800 | POINT (-111.5841 41.83327) | USGS | U.S. Geological Survey | 10107800 | TEMPLE FORK NEAR LOGAN, UTAH | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 10 | USGS-10108000 | POINT (-111.78411 41.74438) | USGS | U.S. Geological Survey | 10108000 | UTAH POWER AND LIGHT TAILRACE NR LOGAN UTAH | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 11 | USGS-10108500 | POINT (-111.7855 41.74576) | USGS | U.S. Geological Survey | 10108500 | LOGAN HYD P AN SM CA N LOGAN UTAH | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 12 | USGS-10109000 | POINT (-111.78398 41.74355) | USGS | U.S. Geological Survey | 10109000 | LOGAN RIVER ABOVE STATE DAM, NEAR LOGAN, UT | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | WDR UT-74-1: Drainage area. WDR UT-96-1:1995, ... | 2017-11-13T06:00:00+00:00 | NaN |
| 13 | USGS-10109001 | POINT (-111.78439 41.74438) | USGS | U.S. Geological Survey | 10109001 | COM F LOGAN R AB ST D AND CACHE HL CAN NR LOGA... | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | <p>WDR UT-04-1: Discharge.</p>\n<p>Revision: T... | 2017-11-13T06:00:00+00:00 | 2024-01-16T17:25:42.927000+00:00 |
| 14 | USGS-10111700 | POINT (-111.56743 41.59438) | USGS | U.S. Geological Survey | 10111700 | BLACKSMITH F B MILL C N HYRUM UT | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 15 | USGS-10112000 | POINT (-111.61743 41.6166) | USGS | U.S. Geological Survey | 10112000 | BLACKSMITH F A H RAN N HYRUM UTAH | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 16 | USGS-10112500 | POINT (-111.68966 41.62771) | USGS | U.S. Geological Survey | 10112500 | BLACKSMITH FK AT MUN. POWERPLANT, NR HYRUM, UT | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 17 | USGS-10113500 | POINT (-111.73616 41.62401) | USGS | U.S. Geological Survey | 10113500 | BLACKSMITH FORK AB UP and L CO.'S DAM NR HYRUM... | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | WSP 1514: 1925. WDR UT-74-1: Drainage area. | 2017-11-13T06:00:00+00:00 | 2025-12-04T20:59:31.117000+00:00 |
| 18 | USGS-10114500 | POINT (-111.80077 41.62771) | USGS | U.S. Geological Survey | 10114500 | BLACKSMITH FK BL UP&L PLANT, NR HYRUM, UT | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 19 | USGS-10115200 | POINT (-111.88633 41.72076) | USGS | U.S. Geological Survey | 10115200 | LOGAN RIVER BLW BLACKSMITH FORK NR LOGAN, UTAH | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 20 | USGS-414048111495101 | POINT (-111.83083 41.68) | USGS | U.S. Geological Survey | 414048111495101 | Blacksmithsfork at 2900 S. nr Millville, UT | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 21 | USGS-414258111502001 | POINT (-111.83889 41.71611) | USGS | U.S. Geological Survey | 414258111502001 | Logan River at golf course road | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 22 | USGS-414308111564101 | POINT (-111.94472 41.71889) | USGS | U.S. Geological Survey | 414308111564101 | Little Bear at 600 S. nr Mendon, UT | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 23 | USGS-414314111553801 | POINT (-111.92722 41.72056) | USGS | U.S. Geological Survey | 414314111553801 | Spring Creek at 600 S. near Logan, UT | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 24 | USGS-414500112000000 | POINT (-112.00078 41.74993) | USGS | U.S. Geological Survey | 414500112000000 | COM FLOW BEAR AREA GSL INFLOW GROUP 1 | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 25 | USGS-414500112000100 | POINT (-112.00106 41.74993) | USGS | U.S. Geological Survey | 414500112000100 | COM FLOW BEAR AREA GSL INFLOW GROUP 2 | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 26 | USGS-414500112000200 | POINT (-112.00134 41.74993) | USGS | U.S. Geological Survey | 414500112000200 | COM FLOW BEAR AREA GSL INFLOW GROUP 3 | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 27 | USGS-414541111544201 | POINT (-111.91167 41.76139) | USGS | U.S. Geological Survey | 414541111544201 | Logan WWTP Outflow nr Logan, UT | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
| 28 | USGS-414615111544301 | POINT (-111.91188 41.77079) | USGS | U.S. Geological Survey | 414615111544301 | Swift Slough at 1300 East nr Logan UT | 49 | US | United States of America | 49 | ... | NaT | None | None | None | NaN | NaN | None | NaN | NaN | NaN |
29 rows × 44 columns