Add waterdata.get_combined_metadata for combined location + time-series inventory

[thodson-usgs]

Closes #263.

Summary

Wraps the Water Data API's combined-metadata collection, which joins the monitoring-locations catalog with the time-series-metadata catalog and returns one row per (location, parameter, statistic) inventory entry. Each row carries every column from both source endpoints, so any location attribute (state, HUC, site type, drainage area, well-construction depth, …) can be combined with any time-series attribute (parameter code, statistic, data type, period of record, …) in a single query — making this the most flexible "what data is available" endpoint in the API.

Mirrors R's read_waterdata_combined_meta.

Implementation note

The function is a thin parameter declaration plus a service / output_id pair ("combined-metadata", "combined_meta_id"), then a single call to the existing get_ogc_data(args, output_id, service). The lower-level helpers (_switch_arg_id, _switch_properties_id, _construct_api_requests, _walk_pages) are all already service-agnostic — they derive the wire-format id field and URL path from the service name — so no infrastructure changes were required.

The parameter list mirrors the live combined-metadata queryables endpoint (https://api.waterdata.usgs.gov/ogcapi/v0/collections/combined-metadata/queryables?f=json). The R signature includes computation_period_identifier, but it is not in this collection's queryables list (it is in time-series-metadata queryables), so it was omitted here.

Live API examples

from dataretrieval.waterdata import get_combined_metadata

# All time series and field measurements at a single site (R example)
df, md = get_combined_metadata(monitoring_location_id="USGS-05407000")
# 14 rows; columns include monitoring_location_id, parameter_code, data_type,
# begin, end, drainage_area, etc.

# Multi-site (forces POST path), filtered by parameter
df, md = get_combined_metadata(
    monitoring_location_id=["USGS-07069000", "USGS-07064000", "USGS-07068000"],
    parameter_code="00060",
)
# 12 rows across the 3 sites, all parameter_code == "00060"

# Inventory across multiple HUCs, restricted to streams and springs
df, md = get_combined_metadata(
    hydrologic_unit_code=["11010008", "11010009"],
    site_type=["Stream", "Spring"],
)

Test plan

• test_get_combined_metadata — single-site live query; asserts presence of merged columns from both source catalogs (monitoring_location_id, parameter_code, data_type, drainage_area).
• test_get_combined_metadata_multi_site_post — multi-site live query that forces the POST path; asserts the result respects the multi-value filter and the parameter filter.
• All 30 tests/waterdata_test.py tests pass.

[Copilot]

Pull request overview

Adds a new high-level Water Data API wrapper, waterdata.get_combined_metadata(...), exposing the Water Data API’s combined-metadata OGC collection to retrieve a merged inventory of monitoring-location and time-series metadata in a single query.

Changes:

• Introduced get_combined_metadata in dataretrieval.waterdata.api (thin wrapper around existing get_ogc_data for the combined-metadata service).
• Exported the new function from dataretrieval.waterdata for public use.
• Added two live/integration tests and documented the addition in NEWS.md.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
dataretrieval/waterdata/api.py	Adds get_combined_metadata wrapper function and its docstring/signature.
dataretrieval/waterdata/__init__.py	Re-exports get_combined_metadata in the module public API.
tests/waterdata_test.py	Adds live tests for single-site and multi-site (POST path) combined metadata queries.
NEWS.md	Adds release-note entry describing the new function.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.