Data files from the STAC API¶
The USGS Water Data STAC API lists data files: each item describes one file, and its
assets link to that file. WaterDataSTAC queries it at
api.waterdata.usgs.gov/stac/v0/ with the same methods and query forms as the other
services, one collection at a time. On 2026-11-13 it served three collections:
continuous and daily, Parquet files per monitoring location, and ratings, the
stage-discharge rating files.
The API key¶
WaterDataSTAC sends the key in USGS_STAC_API_KEY, or in USGS_API_KEY when that is
unset, in the X-Api-Key header. A download that carries a key counts against that
key's hourly limit, one request per file and one per range request, so a reader such as
DuckDB that fetches a Parquet file in pieces spends several. USGS suggests a separate
key for this service, which keeps that traffic off the OGC API quota. A download without
a key reports no rate-limit headers, and USGS does not document the limit it gets.
Finding files¶
The rating files of the Potomac River gage:
from water_ogcapi import WaterDataSTAC
SITE = ["USGS-01646500"]
with WaterDataSTAC() as stac:
result = stac.collect("ratings", ids=SITE, id_property="monitoring_location_id")
for item in result.geojson["features"]:
print(item["id"], item["properties"]["file_type"], item["assets"]["data"]["href"])
A CQL2-JSON filter, and ids, go in the query of a GET, since the service refuses a
POST to its items. The service refuses a GET URL past about 2 KB with a 403, so a
site list given as ids runs as concurrent pieces of 50 sites, or of sites_per_piece.
A CQL2-Text IN list is sent whole, so give a long site list as ids. A page holds up
to 1,000 items unless params set a limit, and 10,000 at most. The service has no
schema endpoint, so schema() raises ServiceError.
The items carry site metadata, so a CQL2-Text LIKE selects a basin by its hydrologic
unit code prefix:
with WaterDataSTAC() as stac:
basin = stac.collect("daily", filter="hydrologic_unit_code LIKE '02070008%'")
print(len(basin.geojson["features"]), "sites with daily values")
The items do not list parameters, periods, or approval status. To find the files of the
sites that measure discharge, ask the OGC API for their time series first, through
combined-metadata, then pass the sites to WaterDataSTAC:
from water_ogcapi import WaterData
with WaterData() as wd:
series = wd.collect(
"combined-metadata",
filter="hydrologic_unit_code LIKE '02070008%' AND parameter_code = '00060' "
"AND data_type = 'Continuous values'",
)
sites = sorted({f["properties"]["monitoring_location_id"] for f in series.geojson["features"]})
with WaterDataSTAC() as stac:
files = stac.collect("continuous", ids=sites, id_property="monitoring_location_id")
print(len(sites), "sites,", len(files.geojson["features"]), "items")
Downloading a file¶
Client.download() fetches a file to disk, creating its folder, as
Transport.download() does from async code:
import tempfile
from pathlib import Path
from water_ogcapi import Client
base = next(f for f in result.geojson["features"] if f["properties"]["file_type"] == "base")
with Client() as client:
path = Path(tempfile.mkdtemp()) / "USGS-01646500.base.rdb"
download = client.download(base["assets"]["data"]["href"], path)
print(download.size, "bytes in", download.path.name)
Pass headers={"X-Api-Key": ...} to send a key with a download.
Reading a Parquet file from daily or continuous needs pyarrow or another Parquet
reader. A continuous item has two files: current, about the last 150 days, and
historical, everything older. If both hold the same time_series_id and time, keep
the row with the latest last_modified.
Searching several collections¶
The service also answers /search, which queries several collections at once.
WaterDataSTAC leaves it to pystac-client,
whose search() posts the query and follows each next link with the body it carries:
import os
from pystac_client import Client as STACClient
catalog = STACClient.open(
"https://api.waterdata.usgs.gov/stac/v0/",
headers={"X-Api-Key": os.environ["USGS_STAC_API_KEY"]},
)
search = catalog.search(
collections=["daily", "continuous"],
filter={"op": "=", "args": [{"property": "monitoring_location_id"}, "USGS-01646500"]},
filter_lang="cql2-json",
)
for item in search.items():
print(item.collection_id, item.id, list(item.assets))
The service takes only cql2-json in a POST body.