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
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_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.")
Retrieved information about 1 parameter code.
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])
| parameter_cd | group | parm_nm | epa_equivalence | result_statistical_basis | result_time_basis | result_weight_basis | result_particle_size_basis | result_sample_fraction | result_temperature_basis | CASRN | SRSName | parm_unit | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 00400 | Physical | pH, water, unfiltered, field, standard units | Agree | NaN | NaN | NaN | NaN | Total | NaN | pH | std units |