feat(waterdata): enable arbitrary queryables as passthrough filters

The OGC data getters (`get_daily`, `get_continuous`, `get_peaks`, ...) exposed
~11 of each collection's ~50 queryables as named params; the rest — mostly the
shared monitoring-location attributes (`state_name`, `county_code`, `site_type`,
`altitude`, ...) now filterable on the data endpoints — were reachable only via
the raw `filter` CQL.

Accept any queryable as a passthrough kwarg: each OGC getter gains
`**queryables`, and the shared `_get_args` flattens it so an extra filter such
as `state_name="Wisconsin"` is normalized and sent exactly like a named param.
The service itself validates names (an unknown one returns HTTP 400 → typed
error), so no client-side queryable list is bundled.

The passthrough is provisional (see the PR description for the trade-off vs.
explicit per-property keyword arguments).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sjb14HkwuCydKSKMsaXsgd

Author: thodson-usgs

dataretrieval/waterdata/api.py

@@ -75,6 +75,7 @@ def get_daily(
     filter: str | None = None,
     filter_lang: FILTER_LANG | None = None,
     convert_type: bool = True,
+    **queryables: Any,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Daily data provide one data value to represent water conditions for the
     day.
@@ -207,6 +208,13 @@ def get_daily(
         and the lexicographic-comparison pitfall.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
+    **queryables : string or iterable of strings, optional
+        Any other queryable property of this collection, passed through as a
+        server-side filter (e.g. ``state_name="Wisconsin"``,
+        ``site_type_code="ST"``). See :func:`get_queryables` for a collection's
+        queryable properties; an unknown name is rejected by the service with a
+        ``DataRetrievalError`` (HTTP 400). This passthrough is provisional and
+        may be superseded by explicit per-property keyword arguments.
 
     Returns
     -------
@@ -296,6 +304,7 @@ def get_continuous(
     filter: str | None = None,
     filter_lang: FILTER_LANG | None = None,
     convert_type: bool = True,
+    **queryables: Any,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """
     Continuous data provide instantaneous water conditions.
@@ -422,6 +431,13 @@ def get_continuous(
         and the lexicographic-comparison pitfall.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
+    **queryables : string or iterable of strings, optional
+        Any other queryable property of this collection, passed through as a
+        server-side filter (e.g. ``state_name="Wisconsin"``,
+        ``site_type_code="ST"``). See :func:`get_queryables` for a collection's
+        queryable properties; an unknown name is rejected by the service with a
+        ``DataRetrievalError`` (HTTP 400). This passthrough is provisional and
+        may be superseded by explicit per-property keyword arguments.
 
     Returns
     -------
@@ -521,6 +537,7 @@ def get_monitoring_locations(
     filter: str | None = None,
     filter_lang: FILTER_LANG | None = None,
     convert_type: bool = True,
+    **queryables: Any,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Location information is basic information about the monitoring location
     including the name, identifier, agency responsible for data collection, and
@@ -739,6 +756,13 @@ def get_monitoring_locations(
         and the lexicographic-comparison pitfall.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
+    **queryables : string or iterable of strings, optional
+        Any other queryable property of this collection, passed through as a
+        server-side filter (e.g. ``state_name="Wisconsin"``,
+        ``site_type_code="ST"``). See :func:`get_queryables` for a collection's
+        queryable properties; an unknown name is rejected by the service with a
+        ``DataRetrievalError`` (HTTP 400). This passthrough is provisional and
+        may be superseded by explicit per-property keyword arguments.
 
     Returns
     -------
@@ -809,6 +833,7 @@ def get_time_series_metadata(
     filter: str | None = None,
     filter_lang: FILTER_LANG | None = None,
     convert_type: bool = True,
+    **queryables: Any,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Daily data and continuous measurements are grouped into time series,
     which represent a collection of observations of a single parameter,
@@ -976,6 +1001,13 @@ def get_time_series_metadata(
         and the lexicographic-comparison pitfall.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
+    **queryables : string or iterable of strings, optional
+        Any other queryable property of this collection, passed through as a
+        server-side filter (e.g. ``state_name="Wisconsin"``,
+        ``site_type_code="ST"``). See :func:`get_queryables` for a collection's
+        queryable properties; an unknown name is rejected by the service with a
+        ``DataRetrievalError`` (HTTP 400). This passthrough is provisional and
+        may be superseded by explicit per-property keyword arguments.
 
     Returns
     -------
@@ -1081,6 +1113,7 @@ def get_combined_metadata(
     filter: str | None = None,
     filter_lang: FILTER_LANG | None = None,
     convert_type: bool = True,
+    **queryables: Any,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Get combined monitoring-location and time-series metadata.
 
@@ -1183,6 +1216,13 @@ def get_combined_metadata(
         and the lexicographic-comparison pitfall.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
+    **queryables : string or iterable of strings, optional
+        Any other queryable property of this collection, passed through as a
+        server-side filter (e.g. ``state_name="Wisconsin"``,
+        ``site_type_code="ST"``). See :func:`get_queryables` for a collection's
+        queryable properties; an unknown name is rejected by the service with a
+        ``DataRetrievalError`` (HTTP 400). This passthrough is provisional and
+        may be superseded by explicit per-property keyword arguments.
 
     Returns
     -------
@@ -1278,6 +1318,7 @@ def get_latest_continuous(
     filter: str | None = None,
     filter_lang: FILTER_LANG | None = None,
     convert_type: bool = True,
+    **queryables: Any,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """This endpoint provides the most recent observation for each time series
     of continuous data. Continuous data are collected via automated sensors
@@ -1407,6 +1448,13 @@ def get_latest_continuous(
         and the lexicographic-comparison pitfall.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
+    **queryables : string or iterable of strings, optional
+        Any other queryable property of this collection, passed through as a
+        server-side filter (e.g. ``state_name="Wisconsin"``,
+        ``site_type_code="ST"``). See :func:`get_queryables` for a collection's
+        queryable properties; an unknown name is rejected by the service with a
+        ``DataRetrievalError`` (HTTP 400). This passthrough is provisional and
+        may be superseded by explicit per-property keyword arguments.
 
     Returns
     -------
@@ -1479,6 +1527,7 @@ def get_latest_daily(
     filter: str | None = None,
     filter_lang: FILTER_LANG | None = None,
     convert_type: bool = True,
+    **queryables: Any,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Daily data provide one data value to represent water conditions for the
     day.
@@ -1610,6 +1659,13 @@ def get_latest_daily(
         and the lexicographic-comparison pitfall.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
+    **queryables : string or iterable of strings, optional
+        Any other queryable property of this collection, passed through as a
+        server-side filter (e.g. ``state_name="Wisconsin"``,
+        ``site_type_code="ST"``). See :func:`get_queryables` for a collection's
+        queryable properties; an unknown name is rejected by the service with a
+        ``DataRetrievalError`` (HTTP 400). This passthrough is provisional and
+        may be superseded by explicit per-property keyword arguments.
 
     Returns
     -------
@@ -1683,6 +1739,7 @@ def get_field_measurements(
     filter: str | None = None,
     filter_lang: FILTER_LANG | None = None,
     convert_type: bool = True,
+    **queryables: Any,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Field measurements are physically measured values collected during a
     visit to the monitoring location. Field measurements consist of measurements
@@ -1805,6 +1862,13 @@ def get_field_measurements(
         and the lexicographic-comparison pitfall.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
+    **queryables : string or iterable of strings, optional
+        Any other queryable property of this collection, passed through as a
+        server-side filter (e.g. ``state_name="Wisconsin"``,
+        ``site_type_code="ST"``). See :func:`get_queryables` for a collection's
+        queryable properties; an unknown name is rejected by the service with a
+        ``DataRetrievalError`` (HTTP 400). This passthrough is provisional and
+        may be superseded by explicit per-property keyword arguments.
 
     Returns
     -------
@@ -1874,6 +1938,7 @@ def get_field_measurements_metadata(
     filter: str | None = None,
     filter_lang: FILTER_LANG | None = None,
     convert_type: bool = True,
+    **queryables: Any,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Get field-measurement metadata: one row per (location, parameter) series.
 
@@ -1927,6 +1992,13 @@ def get_field_measurements_metadata(
         and the lexicographic-comparison pitfall.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
+    **queryables : string or iterable of strings, optional
+        Any other queryable property of this collection, passed through as a
+        server-side filter (e.g. ``state_name="Wisconsin"``,
+        ``site_type_code="ST"``). See :func:`get_queryables` for a collection's
+        queryable properties; an unknown name is rejected by the service with a
+        ``DataRetrievalError`` (HTTP 400). This passthrough is provisional and
+        may be superseded by explicit per-property keyword arguments.
 
     Returns
     -------
@@ -1999,6 +2071,7 @@ def get_peaks(
     filter: str | None = None,
     filter_lang: FILTER_LANG | None = None,
     convert_type: bool = True,
+    **queryables: Any,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Get the annual peak streamflow / stage record for a monitoring location.
 
@@ -2057,6 +2130,13 @@ def get_peaks(
         and the lexicographic-comparison pitfall.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
+    **queryables : string or iterable of strings, optional
+        Any other queryable property of this collection, passed through as a
+        server-side filter (e.g. ``state_name="Wisconsin"``,
+        ``site_type_code="ST"``). See :func:`get_queryables` for a collection's
+        queryable properties; an unknown name is rejected by the service with a
+        ``DataRetrievalError`` (HTTP 400). This passthrough is provisional and
+        may be superseded by explicit per-property keyword arguments.
 
     Returns
     -------
@@ -2981,6 +3061,7 @@ def get_channel(
     filter: str | None = None,
     filter_lang: FILTER_LANG | None = None,
     convert_type: bool = True,
+    **queryables: Any,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """
     Channel measurements taken as part of streamflow field measurements.
@@ -3110,6 +3191,13 @@ def get_channel(
         and the lexicographic-comparison pitfall.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
+    **queryables : string or iterable of strings, optional
+        Any other queryable property of this collection, passed through as a
+        server-side filter (e.g. ``state_name="Wisconsin"``,
+        ``site_type_code="ST"``). See :func:`get_queryables` for a collection's
+        queryable properties; an unknown name is rejected by the service with a
+        ``DataRetrievalError`` (HTTP 400). This passthrough is provisional and
+        may be superseded by explicit per-property keyword arguments.
 
     Returns
     -------

dataretrieval/waterdata/utils.py

@@ -166,7 +166,18 @@ def _get_args(
     params such as ``water_year``, ``thresholds``, ``boundingBox``) so they
     keep their element types. See :func:`engine._get_args` for the full
     normalization contract.
+
+    A getter's ``**queryables`` passthrough kwargs are collected by ``locals()``
+    under the ``queryables`` key; they are flattened in here, so an extra
+    server-side filter such as ``state_name="Wisconsin"`` is normalized and sent
+    exactly like a named param. See
+    :func:`dataretrieval.waterdata.get_queryables` for each collection's
+    filterable properties (the service rejects an unknown one with a 400).
     """
+    local_vars = dict(local_vars)
+    queryables = local_vars.pop("queryables", None)
+    if queryables:
+        local_vars.update(queryables)
     return _engine_get_args(local_vars, exclude, no_normalize=_NO_NORMALIZE_PARAMS)
 
 

tests/waterdata_queryables_test.py

@@ -26,6 +26,7 @@
 import json
 import re
 from pathlib import Path
+from urllib.parse import parse_qs, urlsplit
 
 import pytest
 
@@ -96,6 +97,67 @@ def test_get_queryables_unknown_collection_raises(httpx_mock):
         waterdata.get_queryables("not-a-collection")
 
 
+# --- passthrough queryables (mocked) ---------------------------------------
+
+_DAILY_ITEMS_RE = re.compile(
+    r"^https://api\.waterdata\.usgs\.gov/ogcapi/v0/collections/daily/items"
+)
+_DAILY_SCHEMA_RE = re.compile(
+    r"^https://api\.waterdata\.usgs\.gov/ogcapi/v0/collections/daily/schema$"
+)
+_EMPTY_FEATURES = {
+    "type": "FeatureCollection",
+    "features": [],
+    "numberReturned": 0,
+    "numberMatched": 0,
+    "links": [],
+}
+
+
+def _mock_daily(httpx_mock):
+    """Mock the two endpoints a ``get_daily`` call touches: the items query and
+    the schema fetch (used for output typing)."""
+    httpx_mock.add_response(method="GET", url=_DAILY_SCHEMA_RE, json={"properties": {}})
+    httpx_mock.add_response(method="GET", url=_DAILY_ITEMS_RE, json=_EMPTY_FEATURES)
+
+
+def _items_query(httpx_mock):
+    """Parsed query string of the ``/items`` request the getter sent."""
+    req = next(r for r in httpx_mock.get_requests() if "/items" in str(r.url))
+    return parse_qs(urlsplit(str(req.url)).query)
+
+
+def test_passthrough_queryables_sent_as_filters(httpx_mock):
+    """An OGC getter forwards queryables that aren't in its explicit signature
+    (e.g. ``state_name``, ``site_type_code``) to the service as query filters,
+    alongside the named params."""
+    _mock_daily(httpx_mock)
+
+    waterdata.get_daily(
+        monitoring_location_id="USGS-05427718",
+        state_name="Wisconsin",
+        site_type_code="ST",
+    )
+
+    qs = _items_query(httpx_mock)
+    assert qs["state_name"] == ["Wisconsin"]
+    assert qs["site_type_code"] == ["ST"]
+    assert qs["monitoring_location_id"] == ["USGS-05427718"]
+
+
+def test_passthrough_list_queryable_is_comma_joined(httpx_mock):
+    """A list-valued passthrough queryable is normalized and comma-joined like a
+    named multi-value param."""
+    _mock_daily(httpx_mock)
+
+    waterdata.get_daily(
+        monitoring_location_id="USGS-05427718",
+        site_type_code=["ST", "LK"],
+    )
+
+    assert _items_query(httpx_mock)["site_type_code"] == ["ST,LK"]
+
+
 # --- live queryables monitor -----------------------------------------------