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
Defaulting to user installation because normal site-packages is not writeable
Requirement already satisfied: dataretrieval in /home/runner/.local/lib/python3.10/site-packages (0.1.dev1+g3ba0c83)
Requirement already satisfied: requests in /home/runner/.local/lib/python3.10/site-packages (from dataretrieval) (2.32.3)
Requirement already satisfied: pandas==2.* in /home/runner/.local/lib/python3.10/site-packages (from dataretrieval) (2.2.3)
Requirement already satisfied: numpy>=1.22.4 in /home/runner/.local/lib/python3.10/site-packages (from pandas==2.*->dataretrieval) (2.1.2)
Requirement already satisfied: python-dateutil>=2.8.2 in /home/runner/.local/lib/python3.10/site-packages (from pandas==2.*->dataretrieval) (2.9.0.post0)
Requirement already satisfied: pytz>=2020.1 in /usr/lib/python3/dist-packages (from pandas==2.*->dataretrieval) (2022.1)
Requirement already satisfied: tzdata>=2022.7 in /home/runner/.local/lib/python3.10/site-packages (from pandas==2.*->dataretrieval) (2024.2)
Requirement already satisfied: charset-normalizer<4,>=2 in /home/runner/.local/lib/python3.10/site-packages (from requests->dataretrieval) (3.4.0)
Requirement already satisfied: idna<4,>=2.5 in /usr/lib/python3/dist-packages (from requests->dataretrieval) (3.3)
Requirement already satisfied: urllib3<3,>=1.21.1 in /usr/lib/python3/dist-packages (from requests->dataretrieval) (1.26.5)
Requirement already satisfied: certifi>=2017.4.17 in /usr/lib/python3/dist-packages (from requests->dataretrieval) (2020.6.20)
Requirement already satisfied: six>=1.5 in /usr/lib/python3/dist-packages (from python-dateutil>=2.8.2->pandas==2.*->dataretrieval) (1.16.0)
Load the package so you can use it along with other packages used in this notebook.
[2]:
from dataretrieval import nwis
from IPython.display import display
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 = nwis.get_info(sites=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])
| agency_cd | site_no | station_nm | site_tp_cd | lat_va | long_va | dec_lat_va | dec_long_va | coord_meth_cd | coord_acy_cd | ... | local_time_fg | reliability_cd | gw_file_cd | nat_aqfr_cd | aqfr_cd | aqfr_type_cd | well_depth_va | hole_depth_va | depth_src_cd | project_no | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | USGS | 10109000 | LOGAN RIVER ABOVE STATE DAM, NEAR LOGAN, UT | ST | 414436.78 | 1114702.33 | 41.74355 | -111.783981 | G | 1 | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
1 rows × 42 columns
Show the data types of the columns in the resulting data frame.
[5]:
print(siteINFO[0].dtypes)
agency_cd object
site_no object
station_nm object
site_tp_cd object
lat_va float64
long_va float64
dec_lat_va float64
dec_long_va float64
coord_meth_cd object
coord_acy_cd int64
coord_datum_cd object
dec_coord_datum_cd object
district_cd int64
state_cd int64
county_cd int64
country_cd object
land_net_ds object
map_nm object
map_scale_fc int64
alt_va float64
alt_meth_cd object
alt_acy_va float64
alt_datum_cd object
huc_cd int64
basin_cd int64
topo_cd float64
instruments_cd object
construction_dt float64
inventory_dt float64
drain_area_va int64
contrib_drain_area_va float64
tz_cd object
local_time_fg object
reliability_cd float64
gw_file_cd object
nat_aqfr_cd float64
aqfr_cd float64
aqfr_type_cd float64
well_depth_va float64
hole_depth_va float64
depth_src_cd float64
project_no float64
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://waterservices.usgs.gov/nwis/site?sites=10109000&siteOutput=Expanded&format=rdb
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 = nwis.get_info(sites=siteIDs)
display(siteINFO_multi[0])
| agency_cd | site_no | station_nm | site_tp_cd | lat_va | long_va | dec_lat_va | dec_long_va | coord_meth_cd | coord_acy_cd | ... | local_time_fg | reliability_cd | gw_file_cd | nat_aqfr_cd | aqfr_cd | aqfr_type_cd | well_depth_va | hole_depth_va | depth_src_cd | project_no | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | USGS | 05114000 | SOURIS RIVER NEAR SHERWOOD, ND | ST | 485924.00 | 1015728.00 | 48.989957 | -101.958335 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 1 | USGS | 09423350 | CARUTHERS C NR IVANPAH CA | ST | 351442.02 | 1151756.36 | 35.245006 | -115.298989 | M | 5 | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
2 rows × 42 columns
Example 3: Get site information for all sites within a state
[8]:
# Get the site information for a state
siteINFO_state = nwis.get_info(stateCd='UT')
display(siteINFO_state[0])
| agency_cd | site_no | station_nm | site_tp_cd | lat_va | long_va | dec_lat_va | dec_long_va | coord_meth_cd | coord_acy_cd | ... | local_time_fg | reliability_cd | gw_file_cd | nat_aqfr_cd | aqfr_cd | aqfr_type_cd | well_depth_va | hole_depth_va | depth_src_cd | project_no | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | USGS | 09163527 | WEST BITTER CREEK NEAR HARLEY DOME, UTAH | ST | 392035.0 | 1090848.0 | 39.343032 | -109.147336 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 1 | USGS | 09163530 | COLORADO RIVER BELOW COLORADO-UTAH STATE LINE | ST | 390518.0 | 1090601.0 | 39.088317 | -109.100945 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 2 | USGS | 09163550 | HARLEY DOME WASH NEAR HARLEY DOME, UTAH | ST | 390925.0 | 1090840.0 | 39.156927 | -109.145114 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 3 | USGS | 09163675 | COTTONWOOD WASH AT I-70, NEAR CISCO, UTAH | ST | 390454.0 | 1091301.0 | 39.081652 | -109.217615 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 4 | USGS | 09163700 | CISCO WASH NEAR CISCO, UTAH | ST | 385750.0 | 1092010.0 | 38.963873 | -109.336784 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 32760 | USGS | 415956112525201 | (B-15- 9)28cbc- 1 | GW | 415956.0 | 1125252.0 | 41.998808 | -112.881929 | M | S | ... | Y | C | YNNNNNNN | NaN | 100VLFL | NaN | 400.0 | NaN | O | NaN |
| 32761 | USGS | 415956112532501 | (B-15- 9)29dbc- 1 | GW | 415956.0 | 1125325.0 | 41.998808 | -112.891096 | M | S | ... | Y | C | YNNNNNNN | NaN | 100VLFL | NaN | 480.0 | NaN | O | NaN |
| 32762 | USGS | 415957112411001 | (B-15- 7)30cbc- 1 | GW | 415957.0 | 1124110.0 | 41.999086 | -112.686923 | M | S | ... | Y | C | YNNNNNNN | NaN | NaN | NaN | 228.0 | NaN | NaN | NaN |
| 32763 | USGS | 415958111242901 | (A-15- 5)32dbb- 1 | GW | 415958.0 | 1112429.0 | 41.999377 | -111.408818 | M | T | ... | Y | U | NYNNNNNN | NaN | NaN | NaN | 191.0 | 191.0 | NaN | NaN |
| 32764 | USGS | 415958112390301 | (B-15- 7)29dac- 1 | GW | 415958.0 | 1123903.0 | 41.999364 | -112.651644 | M | S | ... | Y | C | YNNNNNNN | NaN | NaN | NaN | 175.0 | NaN | NaN | NaN |
32765 rows × 42 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 = nwis.get_info(huc=huc_list, siteType='ST')
display(siteINFO_huc[0])
| agency_cd | site_no | station_nm | site_tp_cd | lat_va | long_va | dec_lat_va | dec_long_va | coord_meth_cd | coord_acy_cd | ... | local_time_fg | reliability_cd | gw_file_cd | nat_aqfr_cd | aqfr_cd | aqfr_type_cd | well_depth_va | hole_depth_va | depth_src_cd | project_no | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | USGS | 10104600 | SOUTH FORK LITTLE BEAR RIVER NEAR AVON, UTAH | ST | 413001.00 | 1114857.00 | 41.500214 | -111.816607 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 1 | USGS | 10104700 | LITTLE BEAR R BL DAVENPORT C NR AVON UT | ST | 413045.00 | 1114840.00 | 41.512436 | -111.811885 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | 4.649001e+08 |
| 2 | USGS | 10104900 | EAST FK LT BEAR RIV AB RESV NR AVON UTAH | ST | 413106.00 | 1114249.00 | 41.518270 | -111.714382 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 3 | USGS | 10105000 | EAST FORK LITTLE BEAR R NR AVON UTAH | ST | 413100.00 | 1114500.00 | 41.516603 | -111.750772 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 4 | USGS | 10105900 | LITTLE BEAR RIVER AT PARADISE, UT | ST | 413432.00 | 1115116.00 | 41.575490 | -111.855220 | M | S | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | 2.474900e+09 |
| 5 | USGS | 10106000 | LITTLE BEAR RIVER NEAR PARADISE, UTAH | ST | 413525.00 | 1115110.00 | 41.590212 | -111.853554 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 6 | USGS | 10107400 | WELLSVILLE-MENDON LOWER CANAL AT WELLSVILLE, UT | ST-CA | 413855.00 | 1115630.00 | 41.648543 | -111.942446 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 7 | USGS | 10107500 | LITTLE BEAR RIVER NEAR HYRUM, UTAH | ST | 413800.00 | 1115300.00 | 41.633266 | -111.884111 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 8 | USGS | 10107600 | LITTLE BEAR RIV AT WELLSVILLE UTAH | ST | 413851.00 | 1115522.00 | 41.647432 | -111.923556 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 9 | USGS | 10107700 | LOGAN RIVER NR GARDEN CITY, UTAH | ST | 415600.00 | 1113400.00 | 41.933264 | -111.567436 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 10 | USGS | 10107800 | TEMPLE FORK NEAR LOGAN, UTAH | ST | 415000.00 | 1113500.00 | 41.833266 | -111.584103 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 11 | USGS | 10108000 | UTAH POWER AND LIGHT TAILRACE NR LOGAN UTAH | ST | 414440.00 | 1114700.00 | 41.744375 | -111.784109 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | 4.649001e+08 |
| 12 | USGS | 10108400 | CACHE HIGHLINE CANAL NEAR LOGAN, UTAH | ST-CA | 414436.15 | 1114543.42 | 41.743375 | -111.762061 | G | 1 | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 13 | USGS | 10108500 | LOGAN HYD P AN SM CA N LOGAN UTAH | ST | 414445.00 | 1114705.00 | 41.745764 | -111.785498 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 14 | USGS | 10109000 | LOGAN RIVER ABOVE STATE DAM, NEAR LOGAN, UT | ST | 414436.78 | 1114702.33 | 41.743550 | -111.783981 | G | 1 | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 15 | USGS | 10109001 | COM F LOGAN R AB ST D AND CACHE HL CAN NR LOGA... | ST | 414440.00 | 1114701.00 | 41.744375 | -111.784387 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 16 | USGS | 10111700 | BLACKSMITH F B MILL C N HYRUM UT | ST | 413540.00 | 1113400.00 | 41.594381 | -111.567433 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | 4.649001e+08 |
| 17 | USGS | 10112000 | BLACKSMITH F A H RAN N HYRUM UTAH | ST | 413700.00 | 1113700.00 | 41.616603 | -111.617435 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 18 | USGS | 10112500 | BLACKSMITH FK AT MUN. POWERPLANT, NR HYRUM, UT | ST | 413740.00 | 1114120.00 | 41.627713 | -111.689660 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 19 | USGS | 10113500 | BLACKSMITH FORK AB UP and L CO.'S DAM NR HYRUM... | ST | 413726.42 | 1114410.19 | 41.624006 | -111.736164 | G | 1 | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 20 | USGS | 10114500 | BLACKSMITH FK BL UP&L PLANT, NR HYRUM, UT | ST | 413740.00 | 1114800.00 | 41.627711 | -111.800775 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 21 | USGS | 10115200 | LOGAN RIVER BLW BLACKSMITH FORK NR LOGAN, UTAH | ST | 414315.00 | 1115308.00 | 41.720764 | -111.886334 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 22 | USGS | 413900111520003 | Ditch 675 ft DS outfall pipe nr Miller Rd,Hyru... | ST-DCH | 413927.14 | 1115208.36 | 41.657539 | -111.868989 | G | S | ... | Y | C | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 23 | USGS | 414048111495101 | Blacksmithsfork at 2900 S. nr Millville, UT | ST | 414048.00 | 1114951.00 | 41.680000 | -111.830833 | G | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | 4.749224e+08 |
| 24 | USGS | 414258111502001 | Logan River at golf course road | ST | 414258.00 | 1115020.00 | 41.716111 | -111.838889 | G | 5 | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | 4.749224e+08 |
| 25 | USGS | 414308111564101 | Little Bear at 600 S. nr Mendon, UT | ST | 414308.00 | 1115641.00 | 41.718889 | -111.944722 | G | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | 4.749224e+08 |
| 26 | USGS | 414314111553801 | Spring Creek at 600 S. near Logan, UT | ST | 414314.00 | 1115538.00 | 41.720556 | -111.927222 | G | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | 4.749224e+08 |
| 27 | USGS | 414500112000000 | COM FLOW BEAR AREA GSL INFLOW GROUP 1 | ST | 414500.00 | 1120000.00 | 41.749928 | -112.000782 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 28 | USGS | 414500112000100 | COM FLOW BEAR AREA GSL INFLOW GROUP 2 | ST | 414500.00 | 1120001.00 | 41.749928 | -112.001059 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 29 | USGS | 414500112000200 | COM FLOW BEAR AREA GSL INFLOW GROUP 3 | ST | 414500.00 | 1120002.00 | 41.749928 | -112.001337 | M | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 30 | USGS | 414541111544201 | Logan WWTP Outflow nr Logan, UT | ST | 414541.00 | 1115442.00 | 41.761389 | -111.911667 | G | F | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | 4.749224e+08 |
| 31 | USGS | 414615111544301 | Swift Slough at 1300 East nr Logan UT | ST | 414614.85 | 1115442.77 | 41.770792 | -111.911881 | G | 5 | ... | Y | NaN | NNNNNNNN | NaN | NaN | NaN | NaN | NaN | NaN | 4.749224e+08 |
32 rows × 42 columns