USGS dataretrieval Python Package get_pmcodes() Examples

This notebook provides examples of using the Python dataretrieval package to retrieve information about USGS parameter codes from NWIS. 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).

For more information about USGS NWIS parameter codes, see: https://help.waterdata.usgs.gov/codes-and-parameters/parameters

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+g2c775e4c4)
Requirement already satisfied: requests in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from dataretrieval) (2.32.5)
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.1)
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.3)
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.6)
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.21.1 in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from requests->dataretrieval) (2.6.3)
Requirement already satisfied: certifi>=2017.4.17 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

Basic Usage

The dataretrieval package has several functions that allow you to retrieve data from different web services. This examples uses the get_pmcodes() function to retrieve information about parameter codes (i.e., observed variables) from NWIS. The following arguments are supported:

Arguments (Additional arguments, if supplied, will be used as query parameters)

  • parameterCd (string): A string containing the parameter code for which information is to be retrieved.

Example 1: Retrieve information for a set of USGS NWIS parameter codes.

[3]:

parameter_codes = nwis.get_pmcodes(["00400"])
print(
    "Retrieved information about " + str(len(parameter_codes[0])) + " parameter code."
)

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[3], line 1
----> 1 parameter_codes = nwis.get_pmcodes(["00400"])
      2 print(
      3     "Retrieved information about " + str(len(parameter_codes[0])) + " parameter code."
      4 )

File /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages/dataretrieval/nwis.py:863, in get_pmcodes(parameterCd, partial, ssl_check)
    858     if len(response.text.splitlines()) < 10:  # empty query
    859         raise TypeError(
    860             "One of the parameter codes or names entered does not"
    861             "return any information, please try a different value"
    862         )
--> 863     return_list.append(_read_rdb(response.text))
    864 else:
    865     raise TypeError("Parameter information (code or name) must be type string")

File /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages/dataretrieval/nwis.py:1350, in _read_rdb(rdb)
   1335 """
   1336 Convert NWIS rdb table into a ``pandas.dataframe``.
   1337
   (...)   1347
   1348 """
   1349 if "<html>" in rdb.lower() or "<!doctype html>" in rdb.lower():
-> 1350     raise ValueError(
   1351         "Received HTML response instead of RDB. This often indicates "
   1352         "that the service has been moved or is currently unavailable."
   1353     )
   1355 count = 0
   1357 for line in rdb.splitlines():
   1358     # ignore comment lines

ValueError: Received HTML response instead of RDB. This often indicates that the service has been moved or is currently unavailable.

Interpreting the Result

The result of calling the get_pmcodes() function is an object that contains a Pandas data frame object and an associated metadata object. The Pandas data frame contains the parameter code information requested.

Once you’ve got the data frame, you can explore the data.

[4]:

# Display the data frame as a table
display(parameter_codes[0])

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[4], line 2
      1 # Display the data frame as a table
----> 2 display(parameter_codes[0])

NameError: name 'parameter_codes' is not defined