USGS Water Resources: The National Water Information System Behind Flood Prediction, Drought Monitoring, and Aquifer Depletion Tracking

Every flood warning that pops up on a phone, every drought map published by a state water agency, and every FEMA flood insurance rate determination for a property near a river ultimately depends on the same infrastructure: the U.S. Geological Survey's National Water Information System. NWIS operates more than 8,000 active streamflow gauging stations across the country—plus thousands of groundwater monitoring wells, water quality sites, and atmospheric deposition stations—and has been collecting continuous hydrologic records at some locations since 1887. Understanding what the system measures, how the data moves from a river gauge to a flood forecast, how it is used to characterize aquifer depletion, and how to access it programmatically is the subject of this piece.

This article covers the USGS water resources mission and its cooperative funding structure; the mechanics of streamflow gauging using acoustic Doppler technology and traditional staff-plate methods; how USGS data feeds the National Weather Service National Water Model and real-time flood forecasting; the National Groundwater Monitoring Network and what it reveals about major aquifer systems including the Ogallala; USGS water quality monitoring through the NAWQA program; the public-facing tools including WaterWatch, StreamStats, and the Water Data for the Nation portal; the 5-year national water use compilation; drought low-flow statistics and their role in NPDES wastewater permitting; the NWIS REST API and its parameter codes; and a worked Python example retrieving five years of daily discharge data for the Missouri River at Hermann, Missouri.

The USGS water resources mission and cooperative program

The U.S. Geological Survey has been the nation's primary federal water data provider since the 1880s, when Congress directed the agency to investigate the water resources of the arid West to inform irrigation policy. That mandate has expanded into the comprehensive National Water Information System, which today publishes continuous streamflow, groundwater level, water quality, and precipitation data from more than 13,000 monitoring locations nationwide. USGS produces the raw measurement record; the EPA, Army Corps of Engineers, and state environmental agencies use that record for regulatory decisions. The distinction matters: USGS measures, it does not regulate. It has no permitting authority over water use or water quality discharges. Its value to the regulatory system is as an independent scientific observer of what is actually happening in rivers, aquifers, and watersheds.

The monitoring network is funded through a cooperative program that has been the backbone of USGS water data collection since the early 20th century. Under this model, USGS provides matching federal funds for gauging stations operated in partnership with state agencies, city utilities, water districts, irrigation authorities, and other local entities. A partner that contributes roughly half the cost of operating a gauge gains access to the entire national NWIS dataset in return. This cooperative structure explains the uneven geographic density of the gauging network: states and municipalities with active water management challenges—drought-prone western states, large metropolitan areas reliant on surface water supplies, and flood-prone river basins where the Corps of Engineers has infrastructure at stake—tend to support denser networks than rural areas where no local entity has funded a partnership. USGS operated approximately 8,200 active streamflow stations as of 2026, plus more than 4,000 groundwater monitoring wells, several hundred water quality monitoring sites, and a network of atmospheric deposition stations contributing to the National Trends Network.

The oldest continuously operating streamflow gauge in the country is the Rio Grande at Embudo, New Mexico, which has been recording stage readings since 1889. Many other major river gauges have records extending into the late 19th or early 20th century, providing a hydrologic baseline that predates most of the engineering infrastructure built in American river basins. This historical depth is one of NWIS's most irreplaceable scientific assets: flood frequency analysis, which underpins everything from FEMA flood maps to bridge sizing standards, depends on long discharge records to estimate the probability of rare high-flow events.

Streamflow gauging: ADCP, staff plates, and discharge calculation

A streamflow gauge does not measure discharge directly. It measures the height of water in the channel—the stage, or gage height, recorded in feet above an arbitrary datum—and converts that height to a discharge estimate using a site-specific rating curve. The rating curve is an empirical relationship between stage and discharge, developed by repeatedly measuring actual flow across a range of water levels at the same location over many years. Each field measurement gives USGS hydrographers one point on the rating curve; the curve is fitted to the scatter of points and updated whenever the channel geometry changes due to sediment deposition, scour, vegetation changes, or ice.

The core field measurement technique for developing and maintaining rating curves is the Acoustic Doppler Current Profiler. An ADCP emits acoustic pulses into the water column and measures the Doppler frequency shift of the return signal from suspended particles moving with the current. By sweeping the instrument across the channel—mounted on a small motorized boat or wading raft—while the ADCP simultaneously records depth and boat position via GPS, USGS hydrographers build a three-dimensional velocity profile of the entire cross section. Discharge is then computed as the integral of velocity across the cross-sectional area, following the fundamental relationship: Q = V × A, where Q is discharge in cubic feet per second (cfs), V is mean cross-sectional velocity, and A is the wetted cross-sectional area. ADCP measurements have largely replaced the older wading-rod method for medium and large rivers, though wading measurements with mechanical current meters are still used for small streams and low flows where ADCP beam geometry becomes problematic.

At the gauge itself, a float or pressure transducer records stage continuously in a stilling well or directly in the stream, transmitting 15-minute readings via satellite telemetry—typically through NOAA's Geostationary Operational Environmental Satellite system or cellular modem—to NWIS servers where they appear publicly within minutes of measurement. This near-real-time availability is essential for flood monitoring: the National Weather Service and state emergency managers are watching the same data streams that USGS publishes to the web.

NWIS distinguishes two data quality levels. Provisional data has passed basic automated range checks but has not yet been reviewed by a USGS hydrographer. It may contain errors from equipment malfunctions, ice formation on the transducer, debris on the staff plate, or sediment changes that have shifted the rating curve. Approved data has been reviewed and certified by a USGS hydrographer, typically within the calendar year following collection. Discharge estimates during equipment failures or ice-affected periods are flagged as estimated rather than rated, signaling that the published value was interpolated or inferred from nearby gauges rather than computed from a valid stage-discharge rating. Analysts using NWIS data for regulatory or engineering purposes should filter on approved, rated records; provisional data is suitable for operational monitoring but carries greater uncertainty.

Annual peak discharge at each gauge—the single highest instantaneous flow recorded each water year—is separately compiled in the USGS peak streamflow database, which extends back to the earliest records at each site. This annual peak series is the foundational input for flood frequency analysis following Bulletin 17C guidelines, the federal standard for estimating exceedance probabilities. The 100-year flood, formally defined as the discharge with a 1% annual exceedance probability, is derived from fitting a Log-Pearson Type III distribution to the annual peak series at each gauge. FEMA uses those frequency estimates, along with hydraulic modeling of channel and floodplain geometry, to produce the Flood Insurance Rate Maps that govern building regulations, mortgage requirements, and flood insurance pricing across the country.

Flood prediction: NWS River Forecast Centers and the National Water Model

USGS gauges are the nerve endings of the national flood prediction system, but the prediction itself is done by the National Weather Service. The NWS operates 13 River Forecast Centers that cover distinct river basins across the country, each using a combination of USGS stage data, weather model precipitation forecasts, and hydrologic routing models to issue river stage forecasts at specific gauge locations. At each forecast point, the NWS has defined four action thresholds calibrated to the historical stage-impact relationship at that location: action stage (when river managers should begin monitoring and preparing), flood stage (when the river overtops its banks and inundation begins), moderate flood stage (significant property flooding), and major flood stage (extensive flooding with widespread impacts to infrastructure and communities). These thresholds are set from historical records and local knowledge accumulated by the River Forecast Centers over decades.

The National Water Model is a joint NWS–USGS effort that extends operational flood prediction far beyond the roughly 4,000 gauge locations where NWS issues explicit forecasts. The NWM is a continental-scale hydrologic model built on the WRF-Hydro modeling framework, representing 2.7 million stream reaches derived from the National Hydrography Dataset at roughly 1-kilometer horizontal resolution. It ingests precipitation, soil moisture, and snowpack information from the NWS analyses and land surface model, routes water through the channel network using physically based hydraulic equations, and produces 15-minute short-range streamflow forecasts (18-hour lookahead), medium-range forecasts (10 days), and long-range ensemble forecasts (30 days) at every modeled reach. The NWM does not replace gauge-based forecasting at major river points, but it provides flow estimates at millions of ungauged locations that would otherwise have no operational flood guidance—a substantial improvement for small-basin flash flood warning and for infrastructure operators who need to know conditions on streams too small to support a USGS gauge.

Groundwater monitoring: NGWMN and major aquifer systems

USGS groundwater monitoring operates through the National Groundwater Monitoring Network, a federal-state partnership that aggregates water level measurements from more than 20,000 wells drawn from USGS, state geological surveys, and other agencies. The network tracks water level trends in the major aquifer systems that supply a large fraction of U.S. irrigation water and many municipal water supplies.

The Ogallala Aquifer—also called the High Plains Aquifer—is the largest groundwater system in the United States, underlying approximately 174,000 square miles of the Great Plains from South Dakota to Texas. It is the primary water source for irrigated agriculture across a region that produces a disproportionate share of U.S. wheat, corn, sorghum, and cotton. Groundwater pumping for irrigation substantially exceeds the aquifer's natural recharge rate, which is slow because the overlying soils and rock formations transmit infiltrating water slowly. The result is a long-term water table decline that USGS has documented continuously since the 1940s. In the southern portions of the aquifer—particularly in Kansas, Oklahoma, and the Texas Panhandle—water levels have declined by more than 150 feet since pre-development conditions, and current depletion rates in the worst-affected areas range from 1 to 3 feet per year. USGS models project that continued pumping at historical rates will exhaust economically accessible groundwater in significant portions of the southern aquifer within decades. The Ogallala irrigates roughly 30% of all groundwater-irrigated cropland in the country; its depletion represents one of the largest long-term water security challenges in North American agriculture.

The Floridan Aquifer System is the largest confined aquifer in the southeastern United States, underlying all of Florida and portions of Georgia, Alabama, and South Carolina. It is a karst limestone aquifer with high transmissivity and natural artesian pressure in many areas. The Floridan is the primary source of drinking water for approximately 10 million people, including the Tampa Bay, Orlando, and Jacksonville metropolitan areas. Unlike the Ogallala, portions of the Floridan receive substantial recharge through sinkholes and losing streams, but heavy pumping in coastal areas has induced saltwater intrusion in some zones, and declining potentiometric surface levels have reduced spring flows at many of Florida's first-magnitude springs.

The Central Valley Aquifer in California underlies the most productive agricultural region in the country. Intensive pumping—accelerated during droughts when surface water deliveries from state and federal water projects are curtailed—has caused dramatic water table declines and, uniquely, significant land subsidence. USGS InSAR satellite measurements have documented land-surface subsidence rates exceeding one foot per year in the worst-affected portions of the San Joaquin Valley, with cumulative subsidence exceeding 30 feet at some locations since the early 20th century. Subsidence permanently reduces the aquifer's storage capacity by compacting clay layers, damages canal infrastructure, and creates differential settlement problems for roads and buildings. USGS collaborates with the California Department of Water Resources to model depletion rates and subsidence under the state's Sustainable Groundwater Management Act.

Water quality monitoring: NAWQA and the Water Quality Portal

The National Water-Quality Assessment program is USGS's systematic, long-term effort to characterize the quality of the nation's streams, rivers, and groundwater. NAWQA began in 1991 and has operated in rotating study units covering major river basins and principal aquifer systems across the country. Unlike regulatory monitoring programs that focus on compliance with specific discharge permits, NAWQA is designed to characterize ambient conditions across entire basins and detect long-term trends driven by land use change, agricultural practices, and emerging contaminants.

NAWQA measures a broad suite of water quality parameters at its basin study sites.Nutrients—nitrate and phosphate—are among the most important, because agricultural fertilizer runoff from Midwest row-crop agriculture is the dominant source of the nutrient loading that drives the hypoxic zone in the Gulf of Mexico each summer. NAWQA data tracks nitrate concentrations in streams draining agricultural watersheds and in the shallow groundwater beneath fertilized fields, providing the empirical basis for models that estimate the load reaching the Mississippi River and ultimately the Gulf. Pesticides— including herbicides like atrazine and glyphosate and insecticides like chlorpyrifos—are monitored in streams and groundwater, with NAWQA providing the national context for state and EPA regulatory decisions. Sediment load data tracks the particulate matter that streams carry, which affects aquatic habitat, reservoir storage capacity, and the fate of sediment-bound contaminants. Emerging contaminants—including per- and polyfluoroalkyl substances (PFAS), pharmaceuticals, and microplastics—have been added to the NAWQA monitoring suite as analytical methods have advanced, with USGS PFAS surveys documenting widespread detections in streams and groundwater nationwide.

At streamflow gauging stations equipped with water quality sensors, USGS measures continuous parameters including specific conductance (a proxy for dissolved solids concentration), pH, water temperature, dissolved oxygen, and turbidity. These sensors transmit data on the same 15-minute telemetry schedule as stage and discharge, providing a real-time view of conditions relevant to aquatic ecology, drinking water treatment, and industrial water use. Dissolved oxygen and water temperature data are particularly important for tracking thermal stress on cold-water fish species such as trout and salmon, whose habitat requirements are sensitive to both the absolute temperature and the duration of warm-water excursions.

The Water Quality Portal is the unified federal water quality data discovery system, aggregating data from USGS NWIS, EPA STORET, and dozens of state environmental agency databases into a single REST API. WQP allows users to query by geographic area, sampling organization, characteristic name (e.g., “Nitrate”), site type, and date range, returning results in multiple formats including CSV, JSON, and OGML. For researchers studying nutrient dynamics, contaminant fate, or long-term water quality trends, WQP provides access to millions of historical chemistry records that would otherwise require navigating separate agency data systems.

Water Data for the Nation: WaterWatch, StreamStats, and WaterNow

USGS has maintained a suite of public-facing data access tools that have evolved as web technology has changed. The legacy NWIS web interface at waterdata.usgs.gov has been progressively replaced by the Water Data for the Nationportal, which provides a modernized map-based interface for discovering and downloading streamflow, groundwater, and water quality data from NWIS. The portal supports responsive mobile access and cleaner data export workflows than the legacy system.

USGS WaterWatch is the real-time flood and drought situational awareness tool, displaying current streamflow conditions at thousands of gauges on a national map color-coded by discharge percentile relative to historical records. Gauges shown in red or dark orange are experiencing flows in the lowest 10th percentile of the historical record for that day of the year—drought or low-flow conditions. Gauges shown in blue or dark blue are in the highest percentiles, indicating flood or near-flood flows. WaterWatch provides an at-a-glance view of whether a basin is wet or dry relative to its historical experience, updated continuously as gauge data arrives. Emergency managers, water utilities, and environmental agencies use WaterWatch as a first look at unfolding drought or flood conditions.

StreamStats is a GIS-based tool that allows users to delineate drainage basins and compute basin characteristics for any point on the stream network, then retrieve regression equations for estimating flood frequencies and other streamflow statistics at ungauged locations. Before StreamStats, a civil engineer designing a bridge culvert or a stormwater facility would need to manually delineate the upstream drainage area from topographic maps and apply regional regression equations from published USGS reports—a multi-hour process prone to digitization error. StreamStats automates the delineation using the National Elevation Dataset and the National Hydrography Dataset, computes basin characteristics such as drainage area, mean basin slope, and percent impervious cover, and returns estimated flood quantiles with uncertainty bounds. StreamStats is now the standard tool for infrastructure permitting that requires hydrologic analysis in jurisdictions where USGS regional regression equations have been developed.

WaterNow is the mobile-optimized interface to NWIS real-time data, designed for field personnel and members of the public who want quick access to current conditions at a specific gauge without navigating the full NWIS portal. It supports text alerts for gauges that cross user-defined stage thresholds, making it practical for riverside property owners, recreational users, and emergency responders who need passive monitoring without continuous screen attention.

National water use surveys: thermoelectric, irrigation, and public supply

Every five years, USGS compiles the National Compilation of Water Use Data, aggregating water withdrawal and consumption estimates by county across eight use categories. The most recent fully published compilation covers 2015; the 2020 compilation was in preparation as of 2026. The survey is not a direct measurement program—most water use is estimated from reported permits, utility records, irrigation acreage, and population data—but it provides the only nationally consistent picture of how water is allocated across competing demands.

Thermoelectric power is consistently the largest single category of freshwater withdrawals, driven by once-through cooling systems at steam-cycle power plants that pass large volumes of river or lake water through condensers and return it to the source at elevated temperatures. The trend toward closed-loop cooling towers, which recirculate the same water and lose it primarily to evaporation rather than to thermal discharge, has significantly reduced withdrawal volumes even as electricity generation has grown. The distinction between withdrawal (water taken from the source) and consumption (water not returned) is critical for thermoelectric plants: once-through systems withdraw enormous volumes but consume relatively little, while cooling towers withdraw less but consume more through evaporation.

Irrigation withdrawals have shown a modest long-term decline as center-pivot and flood irrigation systems give way to drip and micro-irrigation that applies water directly to root zones, reducing evaporative and deep percolation losses. However, groundwater irrigation withdrawals in the High Plains remain substantially above aquifer recharge rates, and surface water irrigation in the arid West continues to strain water-sharing compacts between upstream and downstream states in basins such as the Colorado, Rio Grande, and Arkansas.

Drought and low-flow statistics: the 7Q10 and NPDES permitting

USGS WaterWatch displays current streamflow conditions in terms of percentiles relative to historical records at each gauge for the same day of the year. The standard low-flow alert threshold is the 10th percentile—flows below which the stream has historically been drier than 90% of the time for that date. Below the 10th percentile, WaterWatch classifies conditions as “much below normal.” Flows in the 10th to 24th percentile range are “below normal,” the 25th to 75th percentile range is “normal,” the 76th to 90th percentile is “above normal,” and above the 90th percentile is “much above normal.”

For regulatory water quality permitting, the critical low-flow statistic is the7Q10: the lowest average 7-day flow with a 10-year recurrence interval, or equivalently, the discharge that the stream falls below on average once every 10 years during its worst 7-day period of the year. The 7Q10 is calculated from the USGS annual minimum 7-day flow series at a gauge using frequency analysis methods analogous to flood frequency analysis. EPA requires that NPDES wastewater discharge permits use the 7Q10 as the design low-flow condition for assessing the dilution available to receiving waters. A wastewater treatment plant discharging to a stream must demonstrate that its effluent will meet water quality standards in the receiving water even under 7Q10 conditions— the worst realistic drought scenario that water quality managers must plan against. This means that USGS low-flow statistics, computed from the NWIS historical record, are a direct input to the permit limits that govern every regulated point source discharge in the country.

The 2012 drought illustrated the cascading consequences of low streamflow conditions beyond water quality. The Mississippi River fell to historically low stages through much of the upper and middle portions of the basin, threatening commercial barge navigation on one of the most important freight corridors in North America. The Army Corps of Engineers conducted emergency rock removal at the Chain of Rocks near St. Louis to maintain minimum navigation channel depths, and barge companies imposed cargo restrictions to reduce draft. Hydroelectric generation at Corps and Bureau of Reclamation projects declined as reservoir storage dropped. Water temperatures rose in river reaches with reduced flow, causing fish kills and stress to cold-water species. Agricultural users drawing from shallow groundwater connected to streams found pumping costs rising as water tables dropped with declining stream levels. The USGS streamflow record provided the continuous documentation of how bad conditions were and how they compared to prior drought events—a function no other federal program could provide in real time at the geographic density that emergency response required.

The NWIS REST API: accessing streamflow data programmatically

USGS publishes the full NWIS dataset through a family of REST web services atwaterservices.usgs.gov/nwis/. The services cover instantaneous values (15-minute data), daily values (statistics computed from 15-minute records for each calendar day), statistics (long-term percentile and mean computations), site information, annual peak streamflow, and groundwater levels. All services require no registration or API key for read access, which makes NWIS one of the most accessible major federal data APIs.

The primary query parameters for the daily values service are:

The JSON response wraps time series data in a WaterML 2.0 envelope. The key path to the values array isdata["value"]["timeSeries"][0]["values"][0]["value"], where each element contains a dateTime, a value string, and a qualifiers list. Missing or ice-affected records are encoded as “-999999” and should be filtered before analysis. The USGS also maintains thedataretrieval Python package (previously called PyNWIS), which wraps the REST API in a Pandas-oriented interface and handles the WaterML parsing automatically. For bulk downloads of historical records across large numbers of gauges, the USGS National Geospatial Program also offers web services for the National Hydrography Dataset and associated basin characteristic layers that complement the time series data.

Python: five years of Missouri River discharge with drought shading

The example below queries the NWIS daily values service for mean daily discharge at the Missouri River at Hermann, Missouri (USGS site 06934500), one of the most important monitoring points on the largest tributary of the Mississippi. The gauge has been continuously operated since 1895 and integrates the runoff from 522,000 square miles of the upper Missouri basin. The script computes a 30-day rolling mean, identifies the 10th-percentile drought threshold, shades drought periods on the hydrograph, and annotates the 2012 drought if it falls within the query window.

import requests
import pandas as pd
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
from datetime import date, timedelta

# USGS NWIS Instantaneous / Daily Values REST API
# Docs: https://waterservices.usgs.gov/rest/DV-Service.html
# No API key required for read access.

NWIS_BASE = "https://waterservices.usgs.gov/nwis/dv/"

# Missouri River at Hermann, MO — USGS site 06934500
# One of the longest continuous records in the country (active since 1895)
SITE = "06934500"
PARAM = "00060"        # Discharge (mean daily) in cubic feet per second
STAT  = "00003"        # Mean (statCd)

end_date   = date.today()
start_date = end_date - timedelta(days=5 * 365)   # ~5 years

params = {
    "sites":        SITE,
    "parameterCd":  PARAM,
    "statCd":       STAT,
    "startDT":      str(start_date),
    "endDT":        str(end_date),
    "format":       "json",
}

print("Fetching NWIS daily discharge for site", SITE, "...")
resp = requests.get(NWIS_BASE, params=params, timeout=60)
resp.raise_for_status()
data = resp.json()

# Navigate the WaterML JSON envelope
ts_list = data["value"]["timeSeries"]
if not ts_list:
    raise RuntimeError("No time series returned. Check site number and parameter code.")

ts      = ts_list[0]
values  = ts["values"][0]["value"]
site_nm = ts["sourceInfo"]["siteName"]
print("Site name:", site_nm)

# Build a tidy DataFrame
rows = []
for v in values:
    if v["value"] != "-999999":
        rows.append({
            "date":      pd.to_datetime(v["dateTime"]).normalize(),
            "discharge": float(v["value"]),
            "qualCd":    v.get("qualifiers", [""])[0],
        })

df = pd.DataFrame(rows).sort_values("date").reset_index(drop=True)
print("Records loaded:", len(df))
print("Date range:", str(df["date"].min())[:10], "to", str(df["date"].max())[:10])
print("Median discharge:", round(df["discharge"].median(), 0), "cfs")

# 30-day rolling mean
df["roll30"] = df["discharge"].rolling(window=30, min_periods=15).mean()

# Drought threshold: 10th percentile of the full record
p10 = df["discharge"].quantile(0.10)
print("10th-percentile drought threshold:", round(p10, 0), "cfs")

# Flag drought periods (rolling mean below p10)
df["drought"] = df["roll30"] < p10

# --- Plot ---
fig, ax = plt.subplots(figsize=(12, 5))

# Shade drought periods
in_drought = False
drought_start = None
for i, row in df.iterrows():
    if row["drought"] and not in_drought:
        drought_start = row["date"]
        in_drought = True
    elif not row["drought"] and in_drought:
        ax.axvspan(drought_start, row["date"], color="#f5c36a", alpha=0.35, lw=0)
        in_drought = False
if in_drought:
    ax.axvspan(drought_start, df["date"].iloc[-1], color="#f5c36a", alpha=0.35, lw=0)

# Daily discharge (light)
ax.fill_between(df["date"], df["discharge"], alpha=0.18, color="#0b4a8f", lw=0)
ax.plot(df["date"], df["discharge"], linewidth=0.6, color="#0b4a8f", alpha=0.55,
        label="Daily mean discharge")

# 30-day rolling mean
ax.plot(df["date"], df["roll30"], linewidth=2.0, color="#0b4a8f",
        label="30-day rolling mean")

# 10th-percentile drought threshold
ax.axhline(p10, color="#cc5500", linestyle="--", linewidth=1.2,
           label="10th-percentile drought threshold (" + str(round(p10, 0)) + " cfs)")

# Annotate the 2012 drought if it falls in range
drought_2012 = pd.Timestamp("2012-08-01")
if df["date"].min() <= drought_2012 <= df["date"].max():
    ax.annotate(
        "2012 drought
(Mississippi R. barge
navigation disrupted)",
        xy=(drought_2012, p10 * 0.75),
        xytext=(drought_2012 + timedelta(days=120), p10 * 2.5),
        fontsize=8,
        arrowprops=dict(arrowstyle="->", color="black", lw=0.8),
        ha="left",
    )

ax.set_title("Missouri River at Hermann MO (USGS " + SITE + ") — daily discharge")
ax.set_xlabel("Date")
ax.set_ylabel("Discharge (cfs)")
ax.legend(fontsize=8, loc="upper right")
ax.yaxis.set_major_formatter(
    matplotlib.ticker.FuncFormatter(lambda x, _: str(round(x / 1000)) + "k")
)
fig.tight_layout()
fig.savefig("missouri_river_discharge.png", dpi=150)
print("Plot saved to missouri_river_discharge.png")

# Tabulate drought periods
drought_runs = []
in_d = False
d_start = None
for i, row in df.iterrows():
    if row["drought"] and not in_d:
        d_start = row["date"]
        in_d = True
    elif not row["drought"] and in_d:
        drought_runs.append({"start": str(d_start)[:10],
                             "end": str(row["date"])[:10],
                             "days": (row["date"] - d_start).days})
        in_d = False
if in_d:
    drought_runs.append({"start": str(d_start)[:10],
                         "end": str(df["date"].iloc[-1])[:10],
                         "days": (df["date"].iloc[-1] - d_start).days})

print("\nDrought periods (30-day mean below 10th percentile):")
for d in sorted(drought_runs, key=lambda x: -x["days"])[:5]:
    print("  ", d["start"], "to", d["end"], "—", d["days"], "days")

The script requires only requests,pandas, andmatplotlib, all standard scientific Python dependencies. Running it against the default 5-year window ending today will retrieve roughly 1,800 daily records, compute the 10th-percentile drought threshold (historically around 40,000–50,000 cfs at Hermann depending on the period of record used), and identify any sustained periods when the 30-day rolling mean fell below that threshold. The 2012 drought annotation will appear if the query window extends back far enough to include August 2012, when the Missouri at Hermann reached some of the lowest flows on record outside the 1930s Dust Bowl period.

For analysis requiring the full period of record rather than a 5-year window, replace the start_dateassignment with a fixed date such as "1895-01-01"to retrieve the complete historical record. The API handles large date ranges without pagination, though very long records may take 10–20 seconds to download. The resulting dataset provides the full century-plus perspective needed for flood frequency analysis, drought severity ranking, and trend detection in long-term streamflow records.