Add CQL filter passthrough to OGC waterdata getters

Every `get_*` function that targets an OGC collection (`continuous`,
`daily`, `field_measurements`, `monitoring_locations`,
`time_series_metadata`, `latest_continuous`, `latest_daily`,
`channel`) now accepts `filter` and `filter_lang` kwargs that are
forwarded as the OGC `filter` / `filter-lang` query parameters.

This unlocks server-side expressions that aren't expressible via the
other kwargs. The motivating use case is pulling one-shot windows of
continuous data around many field-measurement timestamps in a single
request via OR'd BETWEEN clauses, instead of N round-trips.

Caveats documented in each docstring and NEWS.md:

- The server currently accepts `cql-text` (default) and `cql-json`;
  `cql2-text` / `cql2-json` are not yet supported.
- Long filters can exceed the URI length limit. A `UserWarning` is
  emitted above 5000 characters and the practical cap is around 75
  OR-clauses before the server returns HTTP 414.

Includes unit tests covering the filter / filter-lang URL
construction for all OGC services and the long-filter warning.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: thodson-usgs

NEWS.md

@@ -1,3 +1,5 @@
+**04/22/2026:** The OGC `waterdata` getters (`get_continuous`, `get_daily`, `get_field_measurements`, and others) now accept `filter` and `filter_lang` kwargs that are passed through to the service's CQL filter parameter. This enables advanced server-side filtering that isn't expressible via the other kwargs — most commonly, OR'ing multiple time ranges into a single request. The server currently accepts `cql-text` (default) and `cql-json`; long filters can exceed the URI length limit, so `dataretrieval` warns above 5000 characters and the practical cap is around 75 OR-clauses before the server returns HTTP 414.
+
 **12/04/2025:** The `get_continuous()` function was added to the `waterdata` module, which provides access to measurements collected via automated sensors at a high frequency (often 15 minute intervals) at a monitoring location. This is an early version of the continuous endpoint and should be used with caution as the API team improves its performance. In the future, we anticipate the addition of an endpoint(s) specifically for handling large data requests, so it may make sense for power users to hold off on heavy development using the new continuous endpoint.
 
 **11/24/2025:** `dataretrieval` is pleased to offer a new module, `waterdata`, which gives users access USGS's modernized [Water Data APIs](https://api.waterdata.usgs.gov/). The Water Data API endpoints include daily values, instantaneous values, field measurements (modernized groundwater levels service), time series metadata, and discrete water quality data from the Samples database. Though there will be a period of overlap, the functions within `waterdata` will eventually replace the `nwis` module, which currently provides access to the legacy [NWIS Water Services](https://waterservices.usgs.gov/). More example workflows and functions coming soon. Check `help(waterdata)` for more information.

dataretrieval/waterdata/api.py

@@ -51,6 +51,8 @@ def get_daily(
     time: str | list[str] | None = None,
     bbox: list[float] | None = None,
     limit: int | None = None,
+    filter: str | None = None,
+    filter_lang: str | None = None,
     convert_type: bool = True,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Daily data provide one data value to represent water conditions for the
@@ -177,6 +179,18 @@ def get_daily(
         allowable limit is 50000. It may be beneficial to set this number lower
         if your internet connection is spotty. The default (NA) will set the
         limit to the maximum allowable limit for the service.
+    filter : string, optional
+        A CQL text or JSON expression passed through to the OGC API
+        ``filter`` query parameter. Commonly used to OR several time
+        ranges into a single request. At the time of writing the server
+        accepts ``cql-text`` (default) and ``cql-json``; ``cql2-text`` /
+        ``cql2-json`` are not yet supported. Long filters can exceed the
+        server's URI length limit: a warning is emitted above 5000
+        characters, and the practical cap is ~75 OR-clauses before the
+        server returns HTTP 414.
+    filter_lang : string, optional
+        Language of the ``filter`` expression, for example ``cql-text``
+        (default) or ``cql-json``. Sent as ``filter-lang`` in the URL.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
 
@@ -228,6 +242,8 @@ def get_continuous(
     last_modified: str | None = None,
     time: str | list[str] | None = None,
     limit: int | None = None,
+    filter: str | None = None,
+    filter_lang: str | None = None,
     convert_type: bool = True,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """
@@ -348,6 +364,18 @@ def get_continuous(
         allowable limit is 10000. It may be beneficial to set this number lower
         if your internet connection is spotty. The default (NA) will set the
         limit to the maximum allowable limit for the service.
+    filter : string, optional
+        A CQL text or JSON expression passed through to the OGC API
+        ``filter`` query parameter. Commonly used to OR several time
+        ranges into a single request. At the time of writing the server
+        accepts ``cql-text`` (default) and ``cql-json``; ``cql2-text`` /
+        ``cql2-json`` are not yet supported. Long filters can exceed the
+        server's URI length limit: a warning is emitted above 5000
+        characters, and the practical cap is ~75 OR-clauses before the
+        server returns HTTP 414.
+    filter_lang : string, optional
+        Language of the ``filter`` expression, for example ``cql-text``
+        (default) or ``cql-json``. Sent as ``filter-lang`` in the URL.
     convert_type : boolean, optional
         If True, the function will convert the data to dates and qualifier to
         string vector
@@ -426,6 +454,8 @@ def get_monitoring_locations(
     time: str | list[str] | None = None,
     bbox: list[float] | None = None,
     limit: int | None = None,
+    filter: str | None = None,
+    filter_lang: str | None = None,
     convert_type: bool = True,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Location information is basic information about the monitoring location
@@ -635,6 +665,18 @@ def get_monitoring_locations(
         The returning object will be a data frame with no spatial information.
         Note that the USGS Water Data APIs use camelCase "skipGeometry" in
         CQL2 queries.
+    filter : string, optional
+        A CQL text or JSON expression passed through to the OGC API
+        ``filter`` query parameter. Commonly used to OR several time
+        ranges into a single request. At the time of writing the server
+        accepts ``cql-text`` (default) and ``cql-json``; ``cql2-text`` /
+        ``cql2-json`` are not yet supported. Long filters can exceed the
+        server's URI length limit: a warning is emitted above 5000
+        characters, and the practical cap is ~75 OR-clauses before the
+        server returns HTTP 414.
+    filter_lang : string, optional
+        Language of the ``filter`` expression, for example ``cql-text``
+        (default) or ``cql-json``. Sent as ``filter-lang`` in the URL.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
 
@@ -697,6 +739,8 @@ def get_time_series_metadata(
     time: str | list[str] | None = None,
     bbox: list[float] | None = None,
     limit: int | None = None,
+    filter: str | None = None,
+    filter_lang: str | None = None,
     convert_type: bool = True,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Daily data and continuous measurements are grouped into time series,
@@ -851,6 +895,18 @@ def get_time_series_metadata(
         allowable limit is 50000. It may be beneficial to set this number lower
         if your internet connection is spotty. The default (None) will set the
         limit to the maximum allowable limit for the service.
+    filter : string, optional
+        A CQL text or JSON expression passed through to the OGC API
+        ``filter`` query parameter. Commonly used to OR several time
+        ranges into a single request. At the time of writing the server
+        accepts ``cql-text`` (default) and ``cql-json``; ``cql2-text`` /
+        ``cql2-json`` are not yet supported. Long filters can exceed the
+        server's URI length limit: a warning is emitted above 5000
+        characters, and the practical cap is ~75 OR-clauses before the
+        server returns HTTP 414.
+    filter_lang : string, optional
+        Language of the ``filter`` expression, for example ``cql-text``
+        (default) or ``cql-json``. Sent as ``filter-lang`` in the URL.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
 
@@ -903,6 +959,8 @@ def get_latest_continuous(
     time: str | list[str] | None = None,
     bbox: list[float] | None = None,
     limit: int | None = None,
+    filter: str | None = None,
+    filter_lang: str | None = None,
     convert_type: bool = True,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """This endpoint provides the most recent observation for each time series
@@ -1026,6 +1084,18 @@ def get_latest_continuous(
         allowable limit is 50000. It may be beneficial to set this number lower
         if your internet connection is spotty. The default (None) will set the
         limit to the maximum allowable limit for the service.
+    filter : string, optional
+        A CQL text or JSON expression passed through to the OGC API
+        ``filter`` query parameter. Commonly used to OR several time
+        ranges into a single request. At the time of writing the server
+        accepts ``cql-text`` (default) and ``cql-json``; ``cql2-text`` /
+        ``cql2-json`` are not yet supported. Long filters can exceed the
+        server's URI length limit: a warning is emitted above 5000
+        characters, and the practical cap is ~75 OR-clauses before the
+        server returns HTTP 414.
+    filter_lang : string, optional
+        Language of the ``filter`` expression, for example ``cql-text``
+        (default) or ``cql-json``. Sent as ``filter-lang`` in the URL.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
 
@@ -1075,6 +1145,8 @@ def get_latest_daily(
     time: str | list[str] | None = None,
     bbox: list[float] | None = None,
     limit: int | None = None,
+    filter: str | None = None,
+    filter_lang: str | None = None,
     convert_type: bool = True,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Daily data provide one data value to represent water conditions for the
@@ -1200,6 +1272,18 @@ def get_latest_daily(
         allowable limit is 50000. It may be beneficial to set this number lower
         if your internet connection is spotty. The default (None) will set the
         limit to the maximum allowable limit for the service.
+    filter : string, optional
+        A CQL text or JSON expression passed through to the OGC API
+        ``filter`` query parameter. Commonly used to OR several time
+        ranges into a single request. At the time of writing the server
+        accepts ``cql-text`` (default) and ``cql-json``; ``cql2-text`` /
+        ``cql2-json`` are not yet supported. Long filters can exceed the
+        server's URI length limit: a warning is emitted above 5000
+        characters, and the practical cap is ~75 OR-clauses before the
+        server returns HTTP 414.
+    filter_lang : string, optional
+        Language of the ``filter`` expression, for example ``cql-text``
+        (default) or ``cql-json``. Sent as ``filter-lang`` in the URL.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
 
@@ -1251,6 +1335,8 @@ def get_field_measurements(
     time: str | list[str] | None = None,
     bbox: list[float] | None = None,
     limit: int | None = None,
+    filter: str | None = None,
+    filter_lang: str | None = None,
     convert_type: bool = True,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Field measurements are physically measured values collected during a
@@ -1366,6 +1452,18 @@ def get_field_measurements(
         allowable limit is 50000. It may be beneficial to set this number lower
         if your internet connection is spotty. The default (None) will set the
         limit to the maximum allowable limit for the service.
+    filter : string, optional
+        A CQL text or JSON expression passed through to the OGC API
+        ``filter`` query parameter. Commonly used to OR several time
+        ranges into a single request. At the time of writing the server
+        accepts ``cql-text`` (default) and ``cql-json``; ``cql2-text`` /
+        ``cql2-json`` are not yet supported. Long filters can exceed the
+        server's URI length limit: a warning is emitted above 5000
+        characters, and the practical cap is ~75 OR-clauses before the
+        server returns HTTP 414.
+    filter_lang : string, optional
+        Language of the ``filter`` expression, for example ``cql-text``
+        (default) or ``cql-json``. Sent as ``filter-lang`` in the URL.
     convert_type : boolean, optional
         If True, converts columns to appropriate types.
 
@@ -2017,6 +2115,8 @@ def get_channel(
     skip_geometry: bool | None = None,
     bbox: list[float] | None = None,
     limit: int | None = None,
+    filter: str | None = None,
+    filter_lang: str | None = None,
     convert_type: bool = True,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """
@@ -2123,6 +2223,18 @@ def get_channel(
         vertical_velocity_description, longitudinal_velocity_description,
         measurement_type, last_modified, channel_measurement_type. The default (NA) will
         return all columns of the data.
+    filter : string, optional
+        A CQL text or JSON expression passed through to the OGC API
+        ``filter`` query parameter. Commonly used to OR several time
+        ranges into a single request. At the time of writing the server
+        accepts ``cql-text`` (default) and ``cql-json``; ``cql2-text`` /
+        ``cql2-json`` are not yet supported. Long filters can exceed the
+        server's URI length limit: a warning is emitted above 5000
+        characters, and the practical cap is ~75 OR-clauses before the
+        server returns HTTP 414.
+    filter_lang : string, optional
+        Language of the ``filter`` expression, for example ``cql-text``
+        (default) or ``cql-json``. Sent as ``filter-lang`` in the URL.
     convert_type : boolean, optional
         If True, the function will convert the data to dates and qualifier to
         string vector

dataretrieval/waterdata/utils.py

@@ -4,6 +4,7 @@
 import logging
 import os
 import re
+import warnings
 from datetime import datetime
 from typing import Any, get_args
 
@@ -419,6 +420,24 @@ def _construct_api_requests(
     if properties:
         params["properties"] = ",".join(properties)
 
+    # Translate CQL filter Python names to the hyphenated URL parameter that
+    # the OGC API expects. The Python kwarg is `filter_lang` because hyphens
+    # aren't valid in Python identifiers.
+    if "filter_lang" in params:
+        params["filter-lang"] = params.pop("filter_lang")
+    # Emit a warning when a long CQL filter is at risk of exceeding the
+    # server's URI length limit (HTTP 414). Empirically, the waterdata
+    # continuous endpoint begins returning 414 around ~7 KB of filter text
+    # (~75 OR-clauses of typical interval form). The threshold here is
+    # conservative.
+    if isinstance(params.get("filter"), str) and len(params["filter"]) > 5000:
+        warnings.warn(
+            "CQL `filter` is longer than 5000 characters; the server may "
+            "return HTTP 414 (URI Too Long). Consider splitting into batched "
+            "requests.",
+            stacklevel=2,
+        )
+
     headers = _default_headers()
 
     if POST:

tests/waterdata_utils_test.py

@@ -1,8 +1,19 @@
+import warnings
 from unittest import mock
+from urllib.parse import parse_qs, urlsplit
 
+import pytest
 import requests
 
-from dataretrieval.waterdata.utils import _get_args, _walk_pages
+from dataretrieval.waterdata.utils import (
+    _construct_api_requests,
+    _get_args,
+    _walk_pages,
+)
+
+
+def _query_params(prepared_request):
+    return parse_qs(urlsplit(prepared_request.url).query)
 
 
 def test_get_args_basic():
@@ -77,3 +88,96 @@ def test_walk_pages_multiple_mocked():
     assert mock_client.send.called
     assert mock_client.request.called
     assert mock_client.request.call_args[0][1] == "https://example.com/page2"
+
+
+def test_construct_filter_passthrough():
+    """`filter` is forwarded verbatim as a query parameter."""
+    expr = (
+        "(time >= '2023-01-06T16:00:00Z' AND time <= '2023-01-06T18:00:00Z') "
+        "OR (time >= '2023-01-10T18:00:00Z' AND time <= '2023-01-10T20:00:00Z')"
+    )
+    req = _construct_api_requests(
+        service="continuous",
+        monitoring_location_id="USGS-07374525",
+        parameter_code="72255",
+        filter=expr,
+    )
+    qs = _query_params(req)
+    assert qs["filter"] == [expr]
+
+
+def test_construct_filter_lang_hyphenated():
+    """The Python kwarg `filter_lang` is sent as URL key `filter-lang`."""
+    req = _construct_api_requests(
+        service="continuous",
+        monitoring_location_id="USGS-07374525",
+        parameter_code="72255",
+        filter="time >= '2023-01-01T00:00:00Z'",
+        filter_lang="cql-text",
+    )
+    qs = _query_params(req)
+    assert qs["filter-lang"] == ["cql-text"]
+    # The underscore form must NOT appear in the URL
+    assert "filter_lang" not in qs
+
+
+def test_construct_long_filter_emits_warning():
+    """CQL filter strings longer than 5000 characters warn about URI limits."""
+    long_clause = "(time >= '2023-01-01T00:00:00Z' AND time <= '2023-01-01T00:30:00Z')"
+    # Build a filter string that comfortably exceeds the threshold
+    big = " OR ".join([long_clause] * 100)
+    assert len(big) > 5000
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        _construct_api_requests(
+            service="continuous",
+            monitoring_location_id="USGS-07374525",
+            filter=big,
+        )
+    matching = [
+        w
+        for w in caught
+        if issubclass(w.category, UserWarning) and "414" in str(w.message)
+    ]
+    seen = [str(w.message) for w in caught]
+    assert matching, f"expected a URI-length warning, got: {seen}"
+
+
+def test_construct_short_filter_does_not_warn():
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        _construct_api_requests(
+            service="continuous",
+            monitoring_location_id="USGS-07374525",
+            filter="time >= '2023-01-01T00:00:00Z'",
+        )
+    assert not [
+        w
+        for w in caught
+        if issubclass(w.category, UserWarning) and "414" in str(w.message)
+    ]
+
+
+@pytest.mark.parametrize(
+    "service",
+    [
+        "daily",
+        "continuous",
+        "monitoring-locations",
+        "time-series-metadata",
+        "latest-continuous",
+        "latest-daily",
+        "field-measurements",
+        "channel-measurements",
+    ],
+)
+def test_construct_filter_on_all_ogc_services(service):
+    """Filter passthrough works uniformly for every OGC collection endpoint."""
+    req = _construct_api_requests(
+        service=service,
+        filter="value > 0",
+        filter_lang="cql-text",
+    )
+    qs = _query_params(req)
+    assert qs["filter"] == ["value > 0"]
+    assert qs["filter-lang"] == ["cql-text"]