USGS dataretrieval Python Package get_discharge_measurements() Examples
This notebook provides examples of using the Python dataretrieval package to retrieve surface water discharge measurement data for a United States Geological Survey (USGS) monitoring site. 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.13/x64/lib/python3.13/site-packages (0.1.dev1+gf10f08b77)
Requirement already satisfied: requests in /opt/hostedtoolcache/Python/3.13.13/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.13/x64/lib/python3.13/site-packages (from dataretrieval) (3.0.2)
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.4)
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: charset_normalizer<4,>=2 in /opt/hostedtoolcache/Python/3.13.13/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.13/x64/lib/python3.13/site-packages (from requests->dataretrieval) (3.13)
Requirement already satisfied: urllib3<3,>=1.26 in /opt/hostedtoolcache/Python/3.13.13/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.13/x64/lib/python3.13/site-packages (from requests->dataretrieval) (2026.4.22)
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
import dataretrieval.waterdata as waterdata
Basic Usage
The dataretrieval package has several functions that allow you to retrieve data from different web services. This examples uses the get_discharge_measurements() function to retrieve surface water discharge measurements for a USGS monitoring site from NWIS. The function has the following arguments:
Arguments (Additional arguments, if supplied, will be used as query parameters)
sites (list of strings): A list of USGS site codes to retrieve data for. If the qwdata parameter site_no is supplied, it will overwrite the sites parameter.
start (string): The beginning date of a period for which to retrieve measurements. If the qwdata parameter begin_date is supplied, it will overwrite the start parameter.
end (string): The ending date of a period for which to retrieve measurements. If the qwdata parameter end_date is supplied, it will overwrite the end parameter.
Example 1: Get all of the surface water measurements for a single site
[3]:
measurements1 = waterdata.get_field_measurements(monitoring_location_id="10109000")
print("Retrieved " + str(len(measurements1[0])) + " data values.")
Retrieved 0 data values.
Interpreting the Result
The result of calling the get_discharge_measurements() function is an object that contains a Pandas data frame object and an associated metadata object. The Pandas data frame contains the discharge measurements for the time period requested.
Once you’ve got the data frame, there’s several useful things you can do to explore the data.
Display the data frame as a table
[4]:
display(measurements1[0])
| geometry | field_measurements_series_id | field_visit_id | parameter_code | monitoring_location_id | observing_procedure_code | observing_procedure | value | unit_of_measure | time | qualifier | vertical_datum | approval_status | measuring_agency | last_modified | control_condition | measurement_rated | field_measurement_id |
|---|
Show the data types of the columns in the resulting data frame.
[5]:
print(measurements1[0].dtypes)
geometry object
field_measurements_series_id object
field_visit_id object
parameter_code object
monitoring_location_id object
observing_procedure_code object
observing_procedure object
value int64
unit_of_measure object
time datetime64[s]
qualifier object
vertical_datum object
approval_status object
measuring_agency object
last_modified datetime64[s]
control_condition object
measurement_rated object
field_measurement_id object
dtype: object
The other part of the result returned from the get_discharge_measurements() 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: " + measurements1[1].url)
The query URL used to retrieve the data from NWIS was: https://api.waterdata.usgs.gov/ogcapi/v0/collections/field-measurements/items?monitoring_location_id=10109000&skipGeometry=False&limit=50000
Additional Examples
Example 2: Get all of the surface water measurements between a start and end date
[7]:
measurements2 = waterdata.get_field_measurements(
monitoring_location_id="10109000", time="2019-01-01/2019-12-31"
)
print("Retrieved " + str(len(measurements2[0])) + " data values.")
display(measurements2[0])
Retrieved 0 data values.
| geometry | field_measurements_series_id | field_visit_id | parameter_code | monitoring_location_id | observing_procedure_code | observing_procedure | value | unit_of_measure | time | qualifier | vertical_datum | approval_status | measuring_agency | last_modified | control_condition | measurement_rated | field_measurement_id |
|---|
Example 3: Get all of the surface water measurements for multiple sites
[8]:
measurements3 = waterdata.get_field_measurements(monitoring_location_id=["01594440", "040851325"])
print("Retrieved " + str(len(measurements3[0])) + " data values.")
display(measurements3[0])
Retrieved 0 data values.
| geometry | field_measurements_series_id | field_visit_id | parameter_code | monitoring_location_id | observing_procedure_code | observing_procedure | value | unit_of_measure | time | qualifier | vertical_datum | approval_status | measuring_agency | last_modified | control_condition | measurement_rated | field_measurement_id |
|---|