USGS dataretrieval Python Package get_reference_table() Examples

This notebook provides examples of using the Python dataretrieval package to retrieve information about USGS parameter codes from the USGS Water Data API. The dataretrieval package provides a collection of functions to get data from the USGS Water Data API and other online sources of hydrology and water quality data, including the United States Environmental Protection Agency (USEPA).

For more information about USGS 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.13/x64/lib/python3.13/site-packages (0.1.dev1+g7f64c2de7)
Requirement already satisfied: httpx in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from dataretrieval) (0.28.1)
Requirement already satisfied: pandas<4.0.0,>=2.0.0 in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from dataretrieval) (3.0.3)
Requirement already satisfied: numpy>=1.26.0 in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from pandas<4.0.0,>=2.0.0->dataretrieval) (2.4.6)
Requirement already satisfied: python-dateutil>=2.8.2 in /opt/hostedtoolcache/Python/3.13.13/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.13/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: anyio in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (4.13.0)
Requirement already satisfied: certifi in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (2026.5.20)
Requirement already satisfied: httpcore==1.* in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (1.0.9)
Requirement already satisfied: idna in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (3.16)
Requirement already satisfied: h11>=0.16 in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpcore==1.*->httpx->dataretrieval) (0.16.0)

Load the package so you can use it along with other packages used in this notebook.

[2]:

from IPython.display import display

import dataretrieval.waterdata as waterdata

Basic Usage

The dataretrieval package has several functions that allow you to retrieve data from the USGS Water Data API. This example uses the get_reference_table() function to retrieve information about parameter codes (i.e., observed variables). The function returns metadata reference tables, which list the range of allowable values for the parameter arguments in the waterdata module. The following arguments are supported:

  • collection (string): The name of the reference table to retrieve. To retrieve parameter codes, use "parameter-codes". Other options include "agency-codes", "site-types", "states", "counties", "statistic-codes", and several more.

  • limit (numeric, optional): Controls the subset of selected features returned in each page. The maximum allowable limit is 50000. The default (None) uses the maximum allowable limit for the service.

  • query (dictionary, optional): A dictionary of query parameters passed to the collection API call. For example, {"id": "00400"} selects a specific parameter code.

Example 1: Retrieve information for a USGS parameter code.

[3]:

parameter_codes = waterdata.get_reference_table(collection="parameter-codes", query={"id": "00400"})
print(
    "Retrieved information about " + str(len(parameter_codes[0])) + " parameter code."
)

Retrieving: parameter-codes · 1 page · 1 rows
No API key detected — register for higher rate limits at https://api.waterdata.usgs.gov/signup/

Retrieved information about 1 parameter code.

Interpreting the Result

Calling get_reference_table() returns a tuple containing a pandas data frame and an associated metadata object. The data frame holds the requested parameter code information, while the metadata object includes the request URL and the query time.

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

[4]:

# Display the data frame as a table
display(parameter_codes[0])
parameter_code parameter_name unit_of_measure parameter_group_code parameter_description medium statistical_basis time_basis weight_basis particle_size_basis sample_fraction temperature_basis epa_equivalence
0 00400 pH std units PHY pH, water, unfiltered, field, standard units Water None None None None Total None Agree