USGS dataretrieval Python Package get_info() Examples
This notebook provides examples of using the Python dataretrieval package to retrieve information about a United States Geological Survey (USGS) monitoring site. 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 get_info() function to retrieve information about USGS monitoring sites. The function has several arguments, depending on the result you want to retrieve:
Major Arguments (Additional arguments, if supplied, will be used as query parameters)
Note: Must specify one major argument.
sites (string or list of strings): 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 of strings): 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 of strings): 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 of strings): Returns only site data for those sites containing the requested USGS parameter codes.
siteType (string or list of strings): 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
NOTE: The following parameters are available via the USGS data retrieval services, but are not yet functional in the dataretrieval Python package
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: Get site information for a USGS NWIS monitoring site
[3]:
# Specify the site you want to retrieve information for
siteID = "10109000"
# Get the site information
siteINFO = waterdata.get_monitoring_locations(monitoring_location_id=siteID)
Interpreting the Result
The result of calling the get_info() function is an object that contains a Pandas data frame object and an associated metadata object. The Pandas data frame contains the site information for the requested site.
Once you’ve got the data frame, there’s several useful things you can do to explore the information about the site.
[4]:
# Display the data frame as a table
display(siteINFO[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
Show the data types of the columns in the resulting data frame.
[5]:
print(siteINFO[0].dtypes)
geometry object
monitoring_location_id object
agency_code object
agency_name object
monitoring_location_number object
monitoring_location_name object
district_code object
country_code object
country_name object
state_code object
state_name object
county_code object
county_name object
minor_civil_division_code object
site_type_code object
site_type object
hydrologic_unit_code object
basin_code object
altitude int64
altitude_accuracy int64
altitude_method_code object
altitude_method_name object
vertical_datum object
vertical_datum_name object
horizontal_positional_accuracy_code object
horizontal_positional_accuracy object
horizontal_position_method_code object
horizontal_position_method_name object
original_horizontal_datum object
original_horizontal_datum_name object
drainage_area int64
contributing_drainage_area int64
time_zone_abbreviation object
uses_daylight_savings object
construction_date datetime64[s]
aquifer_code object
national_aquifer_code object
aquifer_type_code object
well_constructed_depth int64
hole_constructed_depth int64
depth_source_code object
revision_note object
revision_created object
revision_modified object
dtype: object
The other part of the result returned from the get_info() 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: " + siteINFO[1].url)
The query URL used to retrieve the data from NWIS was: https://api.waterdata.usgs.gov/ogcapi/v0/collections/monitoring-locations/items?id=10109000&skipGeometry=False&limit=50000
Additional Examples
Example 2: Get site information for multiple sites in a list
[7]:
# Create a list of the site identifiers you want to retrieve information for
siteIDs = ["05114000", "09423350"]
# Get the site information
siteINFO_multi = waterdata.get_monitoring_locations(monitoring_location_id=siteIDs)
display(siteINFO_multi[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: Get site information for all sites within a state
[8]:
# Get the site information for a state
siteINFO_state = waterdata.get_monitoring_locations(state_code="UT")
display(siteINFO_state[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: Get site information for all “stream” sites 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])
| 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