Expose the Water Data STAC protocol surface

[thodson-usgs]

Summary

Expose the public USGS Water Data STAC protocol surface through the waterdata.stac namespace while keeping the existing analysis-ready ratings workflow on the main waterdata facade.

Current upstream inventory

As verified against the live USGS catalog on 2026-08-21, /stac/v0/collections?limit=100 reports numberMatched: 1 and numberReturned: 1. The sole collection is ratings, containing stage-discharge rating files in three RDB variants: base, corr, and exsa.

This PR therefore does not claim that daily values, continuous values, peaks, field measurements, or other Water Data products are available through STAC. Those products currently belong to the separate /ogcapi/v0 API family. The official STAC documentation says the catalog will provide a wider array of native-format data, but it publishes no additional collection or timetable today.

The generic interface is useful now for raw ratings catalog/item metadata and is deliberately data-driven so newly published collections can be discovered without another public-interface redesign. waterdata.get_ratings() remains the only analysis-ready STAC workflow and continues to download and parse rating assets.

Public interface

Raw STAC documents are grouped under waterdata.stac:

• get_catalog() and get_conformance()
• get_collections() and get_collection()
• get_items() and get_item()
• get_queryables()
• search() using the advertised GET or POST representation

Each helper returns (document, BaseMetadata). Catalog, Collection, GeoJSON Item/ItemCollection, and JSON Schema documents remain unchanged so callers retain standard links, extensions, collection-specific properties, and asset metadata.

The implementation forwards every parameter advertised for these public routes. The upstream pagination field token is exposed as page_token and translated back on the wire, avoiding ambiguity with the package's credential-parameter guard. Internal /_mgmt/ping and /_mgmt/health routes are excluded because they are service operations, not STAC capabilities.

No compatibility aliases are added for the earlier draft names (get_stac_* and search_stac) because that surface has never been released.

Service integration

STAC calls share the Water Data adapter's existing:

• configured base-URL redirection;
• host-scoped API-key handling;
• typed HTTP errors and response metadata; and
• bounded retry policy.

ADR 0012 records why raw protocol-shaped operations use a waterdata.stac namespace while the parsed waterdata.get_ratings() getter remains flat.

Documentation

• README discovery example
• Water Data reference page
• architecture overview and ADR 0012
• NEWS entry describing the raw-document return contract
• executable STAC notebook covering catalog discovery, the current ratings collection, queryables, GET/POST search, pagination, item inspection, asset metadata, and when to use get_ratings()

Validation

• Full offline suite: 1005 passed, 12 deselected; coverage report: 98%
• Focused STAC/public-interface/architecture suite: 108 passed
• Commit hooks: ruff check, ruff format, strict mypy, lint-imports (8 contracts), xenon, complexipy, notebook stripping, and repository hygiene checks
• git diff --check
• Sphinx HTML build under Python 3.12, including the STAC notebook and ADR 0012: succeeded with five known pre-existing warnings
• Squash verification: one commit, with tree f200027e identical to the former five-commit tip

Primary upstream sources

• Live catalog: https://api.waterdata.usgs.gov/stac/v0/
• Live collections: https://api.waterdata.usgs.gov/stac/v0/collections?limit=100
• STAC guide: https://api.waterdata.usgs.gov/docs/stac/
• OpenAPI document: https://api.waterdata.usgs.gov/stac/v0/api
• USGS ratings announcement: https://waterdata.usgs.gov/blog/wdfn-rating-curves/