USGS dataretrieval Python Package Rating Curve Examples
This notebook provides examples of using the Python dataretrieval package to retrieve stage–discharge rating curve data for United States Geological Survey (USGS) streamgages using the USGS Water Data API via the waterdata module. The waterdata module is the recommended way to access USGS water data and replaces the deprecated nwis module.
Note: not all active USGS streamflow gages have traditional rating curves relating stage to discharge.
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
from dataretrieval import waterdata
Basic Usage
This example uses the get_ratings() function to retrieve rating curve data for a monitoring location from the USGS Water Data STAC catalog. Commonly used arguments include:
monitoring_location_id (string or list of strings): USGS monitoring location id(s) in
AGENCY-IDform (e.g."USGS-10109000").file_type (string or list): which rating file(s) to request —
"exsa"(expanded, shift-adjusted; the default),"base", or"corr".
Unlike most waterdata functions, get_ratings() returns a dictionary mapping each feature id (e.g. "USGS-10109000.exsa.rdb") to a parsed pandas data frame.
Example 1: Get the rating curve for a monitoring location
[3]:
# Specify the USGS monitoring location id
site_id = "USGS-10109000"
# Get the (expanded, shift-adjusted) rating curve
ratings = waterdata.get_ratings(monitoring_location_id=site_id, file_type="exsa")
rating = ratings[f"{site_id}.exsa.rdb"]
print("Retrieved " + str(len(rating)) + " rating points.")
Retrieved 409 rating points.
Interpreting the Result
get_ratings() returns a dictionary keyed by feature id; each value is a pandas data frame holding one rating table. For the "exsa" file type the columns are:
INDEP — typically the gage height, in feet
SHIFT — the current shift in the rating for that value of INDEP
DEP — typically the discharge, in cubic feet per second
STOR — an
*indicates the pair is a fixed point of the rating curve
The "base" and "corr" file types provide alternative representations of the rating. You can display the data frame as a table.
[4]:
display(rating)
| INDEP | SHIFT | DEP | STOR | |
|---|---|---|---|---|
| 0 | 1.77 | -0.07 | 7.46 | NaN |
| 1 | 1.78 | -0.07 | 7.87 | NaN |
| 2 | 1.79 | -0.07 | 8.29 | NaN |
| 3 | 1.80 | -0.07 | 8.73 | NaN |
| 4 | 1.81 | -0.07 | 9.18 | NaN |
| ... | ... | ... | ... | ... |
| 404 | 5.81 | 0.00 | 2175.11 | NaN |
| 405 | 5.82 | 0.00 | 2186.34 | NaN |
| 406 | 5.83 | 0.00 | 2197.61 | NaN |
| 407 | 5.84 | 0.00 | 2208.91 | NaN |
| 408 | 5.85 | 0.00 | 2220.24 | * |
409 rows × 4 columns
Show the data types of the columns in the resulting data frame.
[5]:
print(rating.dtypes)
INDEP float64
SHIFT float64
DEP float64
STOR str
dtype: object
Each rating data frame carries provenance in its attrs: attrs["url"] records the catalog asset it was fetched from, and attrs["comment"] holds the RDB header lines (rating id, parameter, last-shifted timestamp, etc.).
[6]:
print("The rating was fetched from: " + rating.attrs["url"])
The rating was fetched from: https://api.waterdata.usgs.gov/stac-files/ratings/USGS.10109000.exsa.rdb
Example 2: Get the rating curve for a different monitoring location
[7]:
site_id = "USGS-01594440"
ratings = waterdata.get_ratings(monitoring_location_id=site_id, file_type="exsa")
rating = ratings[f"{site_id}.exsa.rdb"]
print("Retrieved " + str(len(rating)) + " rating points.")
Retrieved 2426 rating points.