USGS dataretrieval Python Package what_sites() Examples
This notebook provides examples of using the Python dataretrieval package to search NWIS for sites within a region with specific data. 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
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.
[2]:
from IPython.display import display
from dataretrieval import nwis
import dataretrieval.waterdata as waterdata
Basic Usage
The dataretrieval package has several functions that allow you to retrieve data from different web services. This examples uses the what_sites() function to search NWIS for sites within a region with specific data. The function has several arguments, depending on the result you want to retrieve.
Note: Must specify one major argument.
Major Arguments (Additional arguments, if supplied, will be used as query parameters)
sites (string or list): A list of site numbers. Sites may be prefixed with an optional agency code followed by a colon.
stateCd (string): U.S. postal service (2-digit) state code. Only 1 state can be specified per request.
huc (string or list): A list of hydrologic unit codes (HUC) or aggregated watersheds. Only 1 major HUC can be specified per request, or up to 10 minor HUCs. A major HUC has two digits.
bBox (list): A contiguous range of decimal latitude and longitude, starting with the west longitude, then the south latitude, then the east longitude, and then the north latitude with each value separated by a comma. The product of the range of latitude range and longitude cannot exceed 25 degrees. Whole or decimal degrees must be specified, up to six digits of precision. Minutes and seconds are not allowed.
countyCd (string or list): A list of county numbers, in a 5 digit numeric format. The first two digits of a county’s code are the FIPS State Code. (url: https://help.waterdata.usgs.gov/code/county_query?fmt=html)
Minor Arguments
startDt (string): Selects sites based on whether data was collected at a point in time beginning after startDt (start date). Dates must be in ISO-8601 Calendar Date format (for example: 1990-01-01).
endDt (string)
period (string): Selects sites based on whether or not they were active between now and a time in the past. For example, period=P10W will select sites active in the last ten weeks.
modifiedSince (string): Returns only sites where site attributes or period of record data have changed during the request period.
parameterCd (string or list): Returns only site data for those sites containing the requested USGS parameter codes.
siteType (string or list): Restricts sites to those having one or more major and/or minor site types, such as stream, spring or well. For a list of all valid site types see https://help.waterdata.usgs.gov/site_tp_cd. For example, siteType=’ST’ returns streams only.
Formatting Parameters
siteOutput (string ‘basic’ or ‘expanded’): Indicates the richness of metadata you want for site attributes. Note that for visually oriented formats like Google Map format, this argument has no meaning. Note: for performance reasons, siteOutput=’expanded’ cannot be used if seriesCatalogOutput=true or with any values for outputDataTypeCd.
seriesCatalogOutput (boolean): A switch that provides detailed period of record information for certain output formats. The period of record indicates date ranges for a certain kind of information about a site, for example the start and end dates for a site’s daily mean streamflow.
For additional parameter options see https://waterservices.usgs.gov/docs/site-service/site-service-details
Example 1: Retrieve information about sites in Ohio where phosphorus data was collected
[3]:
siteListPhos = waterdata.get_monitoring_locations(state_code="OH")
Interpreting the Result
The result of calling the what_sites() function is an object that contains a Pandas data frame object and an associated metadata object. The Pandas data frame contains the requestes site inventory data.
Once you’ve got the data frame, there’s several useful things you can do to explore the data.
[4]:
# Display the data frame as a table
display(siteListPhos[0])
| 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
The other part of the result returned from the what_sites() 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.
[5]:
print("The query URL used to retrieve the data from NWIS was: " + siteListPhos[1].url)
The query URL used to retrieve the data from NWIS was: https://api.waterdata.usgs.gov/ogcapi/v0/collections/monitoring-locations/items?state_code=OH&skipGeometry=False&limit=50000
Additional Examples
Example 2: Retrieve site information for a single site
[6]:
oneSite = waterdata.get_monitoring_locations(monitoring_location_id="05114000")
display(oneSite[0])
| 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 3: Retrieve site information for a single site and show the result with expanded output
[7]:
oneSite = waterdata.get_monitoring_locations(monitoring_location_id="05114000")
display(oneSite[0])
| 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: Retrieve site information for sites in Utah with daily values data falling within a specified date range
[8]:
UTsites = waterdata.get_monitoring_locations(
state_code="UT"
)
display(UTsites[0])
| 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 5: Retrieve site information for a single site and show the series catalog output
The series catalog output is a list of the parameters that have been collected at that site
[9]:
oneSite = waterdata.get_time_series_metadata(monitoring_location_id="05114000")
display(oneSite[0])
| geometry | time_series_id | unit_of_measure | parameter_name | parameter_code | statistic_id | hydrologic_unit_code | state_name | last_modified | begin | ... | end_utc | computation_period_identifier | computation_identifier | thresholds | sublocation_identifier | primary | monitoring_location_id | web_description | parameter_description | parent_time_series_id |
|---|
0 rows × 22 columns