dataretrieval simplifies the process of loading hydrologic data into Python.
Like the original R version
dataRetrieval, it retrieves major
U.S. Geological Survey (USGS) hydrology data types available on the Web, as well
as data from the Water Quality Portal (WQP), the National Ground-Water
Monitoring Network (NGWMN), and the Network Linked Data Index (NLDI).
Check the NEWS for all updates and announcements.
Install dataretrieval using pip:
pip install dataretrievalOr conda:
conda install -c conda-forge dataretrievalOr directly from GitHub:
pip install git+https://github.com/DOI-USGS/dataretrieval-python.gitAccess USGS water-monitoring data.
Important: Users are strongly encouraged to obtain an API key for higher rate limits. Register for an API key and set it as an environment variable:
import os
os.environ["API_USGS_PAT"] = "your_api_key_here"The following example retrieves daily streamflow data for a specific
monitoring location. The / in the time argument separates the start and
end of the desired range:
from dataretrieval import waterdata
# Get daily streamflow data (returns DataFrame and metadata)
df, metadata = waterdata.get_daily(
monitoring_location_id='USGS-01646500',
parameter_code='00060', # Discharge
time='2024-10-01/2025-09-30'
)
print(f"Retrieved {len(df)} records")
print(f"Site: {df['monitoring_location_id'].iloc[0]}")
print(f"Mean discharge: {df['value'].mean():.2f} {df['unit_of_measure'].iloc[0]}")Retrieve streamflow at multiple locations from October 1, 2024 to the present:
df, metadata = waterdata.get_daily(
monitoring_location_id=["USGS-13018750","USGS-13013650"],
parameter_code='00060',
time='2024-10-01/..'
)
print(f"Retrieved {len(df)} records")Retrieve location information for all monitoring locations categorized as stream sites in Maryland:
# Get monitoring location information
df, metadata = waterdata.get_monitoring_locations(
state='Maryland', # full name, postal code ('MD'), or FIPS ('24')
site_type_code='ST' # Stream sites
)
print(f"Found {len(df)} stream monitoring locations in Maryland")Finally, retrieve continuous (a.k.a. "instantaneous") data for one location. We strongly advise breaking continuous data requests into smaller time windows to avoid timeouts and other issues:
# Get continuous data for a single monitoring location and water year
df, metadata = waterdata.get_continuous(
monitoring_location_id='USGS-01646500',
parameter_code='00065', # Gage height
time='2024-10-01/2025-09-30'
)
print(f"Retrieved {len(df)} continuous gage height measurements")Visit the API Reference for more information and examples on available services and input parameters.
For verbose troubleshooting and support — including the request URL sent to the API — enable debug-level logging:
import logging
logging.basicConfig(level=logging.DEBUG)Access groundwater data aggregated from many state, federal, and local agencies. NGWMN uses the same OGC engine as the Water Data API, so chunking and pagination behave the same way:
from dataretrieval import ngwmn
# Find the groundwater monitoring sites in a state
# (state accepts a full name, a postal code like 'WI', or a FIPS code like '55')
sites, metadata = ngwmn.get_sites(state='Wisconsin')
print(f"Found {len(sites)} NGWMN sites in Wisconsin")
# Pull water levels from the first twenty sites over a time window.
water_levels, metadata = ngwmn.get_water_level(
monitoring_location_id=sites['monitoring_location_id'][:20],
datetime=['2022-01-01', '2024-01-01']
)
print(f"Retrieved {len(water_levels)} water-level observations")Access water quality data from multiple agencies:
from dataretrieval import wqp
# Find water quality monitoring sites (returns a DataFrame and metadata)
sites, metadata = wqp.what_sites(
statecode='US:55', # Wisconsin
siteType='Stream'
)
print(f"Found {len(sites)} stream monitoring sites in Wisconsin")
# Get water quality results
results, metadata = wqp.get_results(
siteid='USGS-05427718',
characteristicName='Temperature, water'
)
print(f"Retrieved {len(results)} temperature measurements")Discover and navigate hydrologic networks:
from dataretrieval import nldi
# Get watershed basin for a stream reach
basin = nldi.get_basin(
feature_source='comid',
feature_id='13293474' # NHD reach identifier
)
print(f"Basin contains {len(basin)} feature(s)")
# Find upstream flowlines
flowlines = nldi.get_flowlines(
feature_source='comid',
feature_id='13293474',
navigation_mode='UT', # Upstream tributaries
distance=50 # km
)
print(f"Found {len(flowlines)} upstream tributaries within 50km")get_daily: Daily statistical summaries (mean, min, max)get_continuous: High-frequency continuous (instantaneous) valuesget_field_measurements: Discrete measurements from field visitsget_monitoring_locations: Site information and metadataget_time_series_metadata: A location's available data parametersget_latest_daily: Most recent daily statistical summaryget_latest_continuous: Most recent high-frequency valueget_stats_por/get_stats_date_range: Daily, monthly, and annual statisticsget_samples: Discrete USGS water-quality samplesget_ratings: Stage-discharge rating curves
get_sites: Groundwater monitoring-location metadata across many agenciesget_water_level: Depth-to-water and water-level observationsget_lithology: Geologic-material logs by depth intervalget_well_construction: Casing, screen, and build-out recordsget_providers: Contributing data-provider organizations
get_dv: Legacy daily statistical dataget_iv: Legacy continuous (instantaneous) dataget_info: Basic site informationget_stats: Statistical summariesget_discharge_peaks: Annual peak discharge events
get_results: Water-quality analytical results from USGS, EPA, and other agencieswhat_sites: Monitoring-location informationwhat_organizations: Data-provider informationwhat_projects: Sampling-project details
get_basin: Watershed boundary for a point or featureget_flowlines: Upstream/downstream flowline navigationget_features: Find monitoring sites, dams, and other features along the networkget_features_by_data_source: Features from a specific data source
Explore additional examples in the
demos
directory, including Jupyter notebooks demonstrating advanced usage patterns.
- Issue tracker: Report bugs and request features at https://github.com/DOI-USGS/dataretrieval-python/issues
- Documentation: https://doi-usgs.github.io/dataretrieval-python/
Contributions are welcome! Please see CONTRIBUTING.md for development guidelines.
This material is partially based upon work supported by the National Science Foundation (NSF) under award 1931297. Any opinions, findings, conclusions, or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the NSF.
This software is preliminary or provisional and is subject to revision. It is being provided to meet the need for timely best science. The software has not received final approval by the U.S. Geological Survey (USGS). No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. The software is provided on the condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from the authorized or unauthorized use of the software.
Hodson, T.O., Hariharan, J.A., Black, S., and Horsburgh, J.S., 2023, dataretrieval (Python): a Python package for discovering and retrieving water data available from U.S. federal hydrologic web services: U.S. Geological Survey software release, https://doi.org/10.5066/P94I5TX3.