Microproduct data guideintermediate

USGS Water Data APIs

Current and historical U.S. streamflow, groundwater, water-quality, and site measurements for building gauge monitors and local water-analysis tools.

Start the guide Open official source

At a glance

Difficulty
Intermediate — some data preparation helps
Size
Small · ≤0.1 GB
Formats
GeoJSON, JSON, CSV
Access
API
API key
Not required
Provider
U.S. Geological Survey
Updates
Near real time
Data terms
U.S. Public Domain / USGS CC0 guidance

From source to product signal

Test a product idea in four steps

The USGS Water Data APIs provide observations and metadata from monitoring locations across the United States. Start with recent discharge at one gauge and compare the latest value with that same bounded sample. Measurements may be provisional; coverage, qualifiers, units, and vertical datum vary by station, and the result is not an official flood warning.

1

Check the setup

  • Python 3.10 or newer
  • A notebook environment such as Jupyter or Google Colab
  • An internet connection
2

Access the data

  1. 1.Read the OGC API documentation and confirm the station, parameter code, and unit.
  2. 2.Request a bounded recent interval for one monitoring location and preserve its qualifiers.
  3. 3.Check station metadata and official warning sources before giving the measurement operational meaning.
Open official source
3

Run the Python example

Install the packages, then run the notebook cell.

python -m pip install pandas requests

from datetime import datetime, timedelta, timezone
import pandas as pd
import requests

end = datetime.now(timezone.utc)
start = end - timedelta(days=7)
response = requests.get(
    "https://api.waterdata.usgs.gov/ogcapi/v0/collections/continuous/items",
    params={
        "f": "json",
        "limit": 1000,
        "datetime": f"{start.isoformat()}/{end.isoformat()}",
        "monitoring_location_id": "USGS-01646500",
        "parameter_code": "00060",
    },
    timeout=30,
)
response.raise_for_status()
streamflow = pd.json_normalize(response.json()["features"])
streamflow["value"] = pd.to_numeric(streamflow["properties.value"], errors="coerce")
streamflow["retrieved_at_utc"] = pd.Timestamp.now(tz="UTC")
print(streamflow[["properties.time", "value", "properties.unit_of_measure", "properties.approval_status", "properties.qualifier"]].tail())
4

Test a useful signal

Compare current streamflow with its recent distribution

Determine where the latest discharge measurement at one gauge falls within the returned seven-day sample.

  1. 01Confirm the station identifier, discharge parameter code, unit, datum context, and sample completeness.
  2. 02Compare the latest numeric value with the sample median and percentile range while retaining approval status and qualifiers.
  3. 03Explain how provisional measurements, station coverage, pagination, and the absence of an official warning threshold limit the result.

Dataset details

U.S. Geological Survey is a government source. Last verified 2026-08-11. Temporal coverage: historical records and near-real-time measurements.

Domains

Water ResourcesHydrologyNatural Hazards

Data types

Time SeriesGeospatialOperational Data

Tasks

Gauge MonitoringTrend AnalysisAnomaly Detection

Geography

United States

Formats

GeoJSONJSONCSV

Provider

U.S. Geological Survey

Data terms

U.S. Public Domain / USGS CC0 guidance