USGS dataretrieval Python Package get_ratings() Examples
This notebook provides examples of using the Python dataretrieval package to retrieve rating curve data for a United States Geological Survey (USGS) streamflow gage. 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
Requirement already satisfied: dataretrieval in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (0.1.dev1+g0aec2c864)
Requirement already satisfied: requests in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from dataretrieval) (2.33.1)
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.2)
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.4)
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.7)
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.26 in /opt/hostedtoolcache/Python/3.13.12/x64/lib/python3.13/site-packages (from requests->dataretrieval) (2.6.3)
Requirement already satisfied: certifi>=2023.5.7 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 nwisfrom dataretrieval import waterdata
import dataretrieval.waterdata as waterdata
Cell In[2], line 3
from dataretrieval import nwisfrom dataretrieval import waterdata
^
SyntaxError: invalid syntax
Basic Usage
The dataretrieval package has several functions that allow you to retrieve data from different web services. This example uses the get_ratings() function to retrieve rating curve data for a monitoring site from USGS NWIS. The following arguments are available:
Arguments (Additional arguments, if supplied, will be used as query parameters)
site (string): A USGS site number. This is usually an 8 digit number as a string. If the nwis parameter site_no is supplied, it will overwrite the site parameter.
base (string): Can be “base”, “corr”, or “exsa”
county (string): County IDs from county lookup or “ALL”
categories (Listlike): List or comma delimited string of Two-letter category abbreviations
NOTE: Not all active USGS streamflow gages have traditional rating curves that relate stage to flow.
Example 1: Get rating data for an NWIS Site
[3]:
# Specify the USGS site number/code
site_id = "10109000"
# Get the rating curve data
ratingData = nwis.get_ratings(site=site_id, file_type="exsa")
print("Retrieved " + str(len(ratingData[0])) + " data values.")
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[3], line 5
1 # Specify the USGS site number/code
2 site_id = "10109000"
3
4 # Get the rating curve data
----> 5 ratingData = nwis.get_ratings(site=site_id, file_type="exsa")
6 print("Retrieved " + str(len(ratingData[0])) + " data values.")
NameError: name 'nwis' is not defined
Interpreting the Result
The result of calling the get_ratings() function is an object that contains a Pandas data frame object and an associated metadata object. The Pandas data frame contains the rating curve data for the requested site.
Once you’ve got the data frame, there’s several useful things you can do to explore the data. You can execute the following code to display the data frame as a table.
If the “type” parameter in the request has a value of “base,” then the columns in the data frame are as follows:
INDEP - typically the gage height in feet
DEP - typically the streamflow in cubic feet per second
STOR - where an “*” indicates that the pair are a fixed point of the rating curve
If the “type” parameter is specified as “exsa,” then an additional column called SHIFT is included that indicates the current shift in the rating for that value of INDEP.
If the “type” parameter is specified as “corr,” then the columns are as follows:
INDEP - typically gage height in feet
CORR - the correction for that value
CORRINDEP - the corrected value for CORR
[4]:
display(ratingData[0])
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[4], line 1
----> 1 display(ratingData[0])
NameError: name 'ratingData' is not defined
Show the data types of the columns in the resulting data frame
[5]:
print(ratingData[0].dtypes)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[5], line 1
----> 1 print(ratingData[0].dtypes)
NameError: name 'ratingData' is not defined
The other part of the result returned from the get_ratings() 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: " + ratingData[1].url)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[6], line 1
----> 1 print("The query URL used to retrieve the data from NWIS was: " + ratingData[1].url)
NameError: name 'ratingData' is not defined
Example 2: Get rating data for a different NWIS site by changing the site_id
[7]:
site_id = "01594440"
data = nwis.get_ratings(site=site_id, file_type="base")
print("Retrieved " + str(len(data[0])) + " data values.")
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[7], line 2
1 site_id = "01594440"
----> 2 data = nwis.get_ratings(site=site_id, file_type="base")
3 print("Retrieved " + str(len(data[0])) + " data values.")
NameError: name 'nwis' is not defined