USGS dataretrieval Python Package Statistics Examples

This notebook provides examples of using the Python dataretrieval package to retrieve summary statistics for observed variables at a United States Geological Survey (USGS) monitoring location using the USGS Water Data API via the waterdata module.

Two statistics functions are demonstrated:

  • get_stats_date_range() — monthly, calendar-year, and water-year summaries (the “observationIntervals” service).

  • get_stats_por() — day-of-year and month-of-year summaries over the full period of record (the “observationNormals” service).

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.18/x64/lib/python3.13/site-packages (0.1.dev1+g55e94617b)
Requirement already satisfied: httpx in /opt/hostedtoolcache/Python/3.13.18/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.18/x64/lib/python3.13/site-packages (from dataretrieval) (3.1.1)
Requirement already satisfied: anyio>=4.0 in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from dataretrieval) (4.16.0)
Requirement already satisfied: numpy>=2.0.2 in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from pandas<4.0.0,>=2.0.0->dataretrieval) (2.5.5)
Requirement already satisfied: python-dateutil>=2.9.0 in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from pandas<4.0.0,>=2.0.0->dataretrieval) (4.0.0)
Requirement already satisfied: idna>=2.8 in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from anyio>=4.0->dataretrieval) (3.20)
Requirement already satisfied: typing_extensions>=4.16.0 in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from anyio>=4.0->dataretrieval) (4.16.0)
Requirement already satisfied: tzdata in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from python-dateutil>=2.9.0->pandas<4.0.0,>=2.0.0->dataretrieval) (2026.6)
Requirement already satisfied: certifi in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (2026.10.23)
Requirement already satisfied: httpcore==1.* in /opt/hostedtoolcache/Python/3.13.18/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (1.0.9)
Requirement already satisfied: h11>=0.16 in /opt/hostedtoolcache/Python/3.13.18/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 matplotlib import ticker

from dataretrieval import waterdata

Basic Usage

This example uses get_stats_date_range() to retrieve monthly and annual statistics for an observed variable at a USGS monitoring location. Commonly used arguments include:

  • monitoring_location_id (string or list of strings): USGS monitoring location id(s), formed as the agency code and site number joined by a hyphen (e.g. "USGS-02319394").

  • parameter_code (string or list of strings): 5-digit USGS parameter code(s), e.g. "00060" (discharge).

  • computation_type (string or list of strings): the statistic(s) to compute — one or more of arithmetic_mean, maximum, median, minimum, percentile.

  • start_date / end_date (string): optionally bound the period summarized, in YYYY-MM-DD format.

Example 1: Get monthly and annual mean discharge for a single monitoring location

[3]:
# Set the parameters needed to retrieve data
site = "USGS-02319394"
parameter_code = "00060"  # Discharge

# Retrieve the statistics (monthly, calendar-year, and water-year means)
x1 = waterdata.get_stats_date_range(
    monitoring_location_id=site,
    parameter_code=parameter_code,
    computation_type="arithmetic_mean",
)
print("Retrieved " + str(len(x1[0])) + " statistic values.")
Retrieving: observationIntervals · 1 page · 344 rows
No API key detected — register for higher rate limits at https://api.waterdata.usgs.gov/signup/
Retrieved 344 statistic values.

Interpreting the Result

Each waterdata function returns a tuple of a pandas data frame and a metadata object. The data frame holds the computed statistics; each row is one interval, identified by the interval_type column (month, calendar_year, or water_year), with the computed statistic in the value column.

Once you’ve got the data frame, there are several useful things you can do to explore the data.

[4]:
# Display the data frame as a table
display(x1[0])
geometry monitoring_location_id monitoring_location_name site_type site_type_code country_code state_code county_code start_date end_date ... percentile sample_count approval_status computation_id computation parameter_code unit_of_measure parent_time_series_id parent_statistic_id parent_statistic_name
0 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2000-11-01 2000-11-30 ... NaN 30 approved 64d51d1b-9d02-41e2-84c2-1a45ce4fc341 arithmetic_mean 00060 ft^3/s dabac917c8ea4f66a163ddc9d3bb4840 00003 Mean
1 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2000-12-01 2000-12-31 ... NaN 31 approved cea9cb69-4153-4c4c-9ba0-23b23fc14519 arithmetic_mean 00060 ft^3/s dabac917c8ea4f66a163ddc9d3bb4840 00003 Mean
2 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2001-01-01 2001-01-31 ... NaN 31 approved 6c2a6470-9ae3-4c9c-a6b3-aadafd342483 arithmetic_mean 00060 ft^3/s dabac917c8ea4f66a163ddc9d3bb4840 00003 Mean
3 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2001-02-01 2001-02-28 ... NaN 28 approved 61b5f8b7-95ad-49e1-9a4a-a4221c98dea4 arithmetic_mean 00060 ft^3/s dabac917c8ea4f66a163ddc9d3bb4840 00003 Mean
4 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2001-03-01 2001-03-31 ... NaN 31 approved e2bfe030-8e66-40e5-810a-8200df7a0fa8 arithmetic_mean 00060 ft^3/s dabac917c8ea4f66a163ddc9d3bb4840 00003 Mean
... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
339 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2021-10-01 2022-09-30 ... NaN 365 approved a143f449-c691-49b1-8cff-46dacc393472 arithmetic_mean 00060 ft^3/s dabac917c8ea4f66a163ddc9d3bb4840 00003 Mean
340 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2022-10-01 2023-09-30 ... NaN 365 approved 7498963b-61c8-464d-8e98-1e0493ea7eef arithmetic_mean 00060 ft^3/s dabac917c8ea4f66a163ddc9d3bb4840 00003 Mean
341 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2023-10-01 2024-09-30 ... NaN 365 approved 3dc450d1-0b54-4038-8612-8f824c436cac arithmetic_mean 00060 ft^3/s dabac917c8ea4f66a163ddc9d3bb4840 00003 Mean
342 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2024-10-01 2025-09-30 ... NaN 365 approved 616a324b-f504-4974-b877-8f0a6e0b5d34 arithmetic_mean 00060 ft^3/s dabac917c8ea4f66a163ddc9d3bb4840 00003 Mean
343 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2025-10-01 2026-02-08 ... NaN 131 approved 5040325f-16e0-4192-9d04-8ef9bd41de72 arithmetic_mean 00060 ft^3/s dabac917c8ea4f66a163ddc9d3bb4840 00003 Mean

344 rows × 22 columns

Show the data types of the columns in the resulting data frame.

[5]:
print(x1[0].dtypes)
geometry                    geometry
monitoring_location_id           str
monitoring_location_name         str
site_type                        str
site_type_code                   str
country_code                     str
state_code                       str
county_code                      str
start_date                       str
end_date                         str
interval_type                    str
value                            str
percentile                   float64
sample_count                   int64
approval_status                  str
computation_id                   str
computation                      str
parameter_code                   str
unit_of_measure                  str
parent_time_series_id            str
parent_statistic_id              str
parent_statistic_name            str
dtype: object

Make a quick time series plot of the annual (calendar-year) mean values.

[6]:
# select the annual (calendar-year) means into a plain DataFrame for plotting.
# The statistics services return a GeoDataFrame carrying a site-point geometry,
# and report numeric values as strings, so we coerce ``value`` to float.
annual = x1[0].loc[
    x1[0]["interval_type"] == "calendar_year", ["start_date", "value"]
].copy()
annual["year"] = annual["start_date"].str[:4].astype(int)
annual["value"] = annual["value"].astype(float)
annual = annual.sort_values("year")

ax = annual.plot(x="year", y="value", legend=False)
ax.xaxis.set_major_formatter(ticker.FormatStrFormatter("%d"))
ax.set_xlabel("Year")
ax.set_ylabel("Annual mean discharge (cfs)")
[6]:
Text(0, 0.5, 'Annual mean discharge (cfs)')
../_images/examples_USGS_WaterData_Statistics_Examples_13_1.png

The other part of the result is a metadata object describing the query that was executed. For example, you can access the URL that was assembled to retrieve the requested data from the USGS Water Data API.

[7]:
print("The query URL used to retrieve the data was: " + x1[1].url)
The query URL used to retrieve the data was: https://api.waterdata.usgs.gov/statistics/v0/observationIntervals?computation_type=arithmetic_mean&monitoring_location_id=USGS-02319394&page_size=1000&parameter_code=00060

Additional Examples

Example 2: Get monthly and annual mean statistics for two monitoring locations

Multiple monitoring locations and parameter codes can be requested at once; only the data that are available are returned.

[8]:
x2 = waterdata.get_stats_date_range(
    monitoring_location_id=["USGS-02319394", "USGS-02171500"],
    parameter_code=["00010", "00060"],
    computation_type="arithmetic_mean",
)
display(x2[0])
Retrieving: observationIntervals · 1 page · 2,132 rows
geometry monitoring_location_id monitoring_location_name site_type site_type_code country_code state_code county_code start_date end_date ... percentile sample_count approval_status computation_id computation parameter_code unit_of_measure parent_time_series_id parent_statistic_id parent_statistic_name
0 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 2005-04-01 2005-04-30 ... NaN 30 approved a84ab6cc-f5a7-4af9-9062-85d2212765ab arithmetic_mean 00010 degC f7db6d5b53e34034bb9f995cd52b0ad0 00001 Max
1 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 2005-05-01 2005-05-31 ... NaN 31 approved dcb2a2c3-d977-4371-9af0-22d4c5581454 arithmetic_mean 00010 degC f7db6d5b53e34034bb9f995cd52b0ad0 00001 Max
2 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 2005-06-01 2005-06-30 ... NaN 28 approved c267d4e9-e0bf-4bf8-a88a-b35c4c0cd327 arithmetic_mean 00010 degC f7db6d5b53e34034bb9f995cd52b0ad0 00001 Max
3 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 2005-07-01 2005-07-31 ... NaN 31 approved a7852b69-6305-4075-bea0-57c2ac49454d arithmetic_mean 00010 degC f7db6d5b53e34034bb9f995cd52b0ad0 00001 Max
4 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 2005-08-01 2005-08-31 ... NaN 31 approved 6a6fd51f-e54e-479f-b3b6-d6b9d493100c arithmetic_mean 00010 degC f7db6d5b53e34034bb9f995cd52b0ad0 00001 Max
... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
2127 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2021-10-01 2022-09-30 ... NaN 351 approved aebad1cc-577b-4119-8a24-60515777a812 arithmetic_mean 00010 degC ea8d8089780f48428cff4a5ba344f1aa 00002 Min
2128 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2022-10-01 2023-09-30 ... NaN 361 approved 1927f2f0-c058-4ec7-b2f2-95d320ac637e arithmetic_mean 00010 degC ea8d8089780f48428cff4a5ba344f1aa 00002 Min
2129 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2023-10-01 2024-09-30 ... NaN 342 approved b43c2c58-8f3e-4a3c-82a5-187f117440db arithmetic_mean 00010 degC ea8d8089780f48428cff4a5ba344f1aa 00002 Min
2130 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2024-10-01 2025-09-30 ... NaN 348 approved 02a8f83a-a63d-4565-9936-b8a09b2d14d6 arithmetic_mean 00010 degC ea8d8089780f48428cff4a5ba344f1aa 00002 Min
2131 POINT (-83.18014 30.41049) USGS-02319394 WITHLACOOCHEE RIVER NR LEE, FLA Stream ST US 12 079 2025-10-01 2026-05-10 ... NaN 216 approved 3a8b8d1c-df67-4e3e-abe6-658db82c4253 arithmetic_mean 00010 degC ea8d8089780f48428cff4a5ba344f1aa 00002 Min

2132 rows × 22 columns

Example 3: Day-of-year mean and median statistics over the period of record

get_stats_por() summarizes the full period of record by day of year (and month of year). Here we request both the mean and median daily statistics for discharge at a monitoring location.

[9]:
x3 = waterdata.get_stats_por(
    monitoring_location_id="USGS-02171500",
    parameter_code="00060",
    computation_type=["arithmetic_mean", "median"],
)
display(x3[0])
Retrieving: observationNormals · 1 page · 756 rows
geometry monitoring_location_id monitoring_location_name site_type site_type_code country_code state_code county_code time_of_year time_of_year_type ... percentile sample_count approval_status computation_id computation parameter_code unit_of_measure parent_time_series_id parent_statistic_id parent_statistic_name
0 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 01-01 day_of_year ... NaN 82 approved e1fdac04-fddc-4567-8b8d-5d93f344d8dc arithmetic_mean 00060 ft^3/s 218ab832dc5a4c4b9fb1d51efa232d15 00003 Mean
1 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 01-02 day_of_year ... NaN 82 approved 6362d803-c3ea-4995-9fed-133fc9e866c3 arithmetic_mean 00060 ft^3/s 218ab832dc5a4c4b9fb1d51efa232d15 00003 Mean
2 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 01-03 day_of_year ... NaN 82 approved 967c4645-1a80-4c7e-85f2-30a6ce168ae9 arithmetic_mean 00060 ft^3/s 218ab832dc5a4c4b9fb1d51efa232d15 00003 Mean
3 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 01-04 day_of_year ... NaN 82 approved 8275a876-ad42-4084-91c9-b651c073130a arithmetic_mean 00060 ft^3/s 218ab832dc5a4c4b9fb1d51efa232d15 00003 Mean
4 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 01-05 day_of_year ... NaN 83 approved 3eb7a658-822d-4764-ba64-f0865b5cc732 arithmetic_mean 00060 ft^3/s 218ab832dc5a4c4b9fb1d51efa232d15 00003 Mean
... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
751 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 08 month_of_year ... 50.0 84 approved 43d2e28e-aec0-43f5-8017-54ecfa00ac05 median 00060 ft^3/s 218ab832dc5a4c4b9fb1d51efa232d15 00003 Mean
752 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 09 month_of_year ... 50.0 84 approved bb3c559a-c817-4a70-b7bd-fff66c634327 median 00060 ft^3/s 218ab832dc5a4c4b9fb1d51efa232d15 00003 Mean
753 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 10 month_of_year ... 50.0 84 approved ff826c80-9362-4c38-827d-1967425e54be median 00060 ft^3/s 218ab832dc5a4c4b9fb1d51efa232d15 00003 Mean
754 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 11 month_of_year ... 50.0 84 approved 9b12252e-b12e-4971-9884-bbeae61dbd21 median 00060 ft^3/s 218ab832dc5a4c4b9fb1d51efa232d15 00003 Mean
755 POINT (-80.14136 33.45378) USGS-02171500 SANTEE RIVER NEAR PINEVILLE, SC Stream ST US 45 015 12 month_of_year ... 50.0 84 approved 1d9e47f5-896e-444c-ad5a-3b5629772d29 median 00060 ft^3/s 218ab832dc5a4c4b9fb1d51efa232d15 00003 Mean

756 rows × 21 columns