Merge remote-tracking branch 'upstream/main' into fix-waterdata-get-multivalue

Author: thodson-usgs

NEWS.md

@@ -1,3 +1,15 @@
+**05/01/2026:** The `nadp` module is now deprecated. Calling any of `get_annual_MDN_map`, `get_annual_NTN_map`, or `get_zip` will emit a `DeprecationWarning`. The module is scheduled for removal on or after **2026-11-01**. NADP is not a USGS data source; users should retrieve NADP data directly from https://nadp.slh.wisc.edu/.
+
+**04/23/2026:** Added `waterdata.get_nearest_continuous(targets, ...)` — for each of N target timestamps, fetches the single continuous observation closest to that timestamp in one HTTP round-trip (auto-chunked when the resulting CQL filter is long, via the facility added in #238). The helper is designed for workflows that pair many discrete-measurement timestamps with surrounding instantaneous data, which the OGC `time` parameter can't express since it only accepts one instant or one interval per request. Ties at window midpoints are resolved per a configurable `on_tie` ∈ {`"first"`, `"last"`, `"mean"`}; the default `window="PT7M30S"` matches a 15-minute continuous gauge.
+
+**04/22/2026:** Highlights since the `v1.1.0` release (2025-11-26), which shipped the `waterdata` module:
+
+- Added `get_channel` for channel-measurement data (#218) and `get_stats_por` / `get_stats_date_range` for period-of-record and daily statistics (#207).
+- Added `get_reference_table` (and made it considerably simpler and faster in #209), then extended it to accept arbitrary collections-API query parameters (#214).
+- Removed the deprecated `waterwatch` module (#228) and several defunct NWIS stubs (#222, #225), and added `py.typed` so `dataretrieval` ships type information to downstream users (#186).
+- Now supports `pandas` 3.x (#221).
+- The OGC `waterdata` getters (`get_continuous`, `get_daily`, `get_field_measurements`, and the six others built on the same OGC collections) 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. A long expression made up of a top-level `OR` chain is transparently split into multiple requests that each fit under the server's URI length limit, and the results are concatenated.
+
 **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/nadp.py

@@ -31,10 +31,22 @@
 
 import io
 import re
+import warnings
 import zipfile
 
 import requests
 
+_DEPRECATION_MESSAGE = (
+    "The `nadp` module is deprecated and will be removed from `dataretrieval` "
+    "on or after 2026-11-01. NADP is not a USGS data source; please retrieve "
+    "NADP data directly from https://nadp.slh.wisc.edu/."
+)
+
+
+def _warn_deprecated():
+    warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=3)
+
+
 NADP_URL = "https://nadp.slh.wisc.edu"
 NADP_MAP_EXT = "filelib/maps"
 
@@ -107,6 +119,8 @@ def get_annual_MDN_map(measurement_type, year, path):
         ... )
 
     """
+    _warn_deprecated()
+
     url = f"{NADP_URL}/{NADP_MAP_EXT}/MDN/grids/"
 
     filename = f"Hg_{measurement_type}_{year}.zip"
@@ -160,6 +174,8 @@ def get_annual_NTN_map(measurement_type, measurement=None, year=None, path="."):
         ... )
 
     """
+    _warn_deprecated()
+
     url = f"{NADP_URL}/{NADP_MAP_EXT}/NTN/grids/{year}/"
 
     filename = f"{measurement_type}_{year}.zip"
@@ -195,6 +211,8 @@ def get_zip(url, filename):
         finish docstring
 
     """
+    _warn_deprecated()
+
     req = requests.get(url + filename)
     req.raise_for_status()
 

dataretrieval/nldi.py

@@ -13,6 +13,7 @@
 NLDI_API_BASE_URL = "https://api.water.usgs.gov/nldi/linked-data"
 _AVAILABLE_DATA_SOURCES = None
 _CRS = "EPSG:4326"
+_VALID_NAVIGATION_MODES = ("UM", "DM", "UT", "DD")
 
 
 def _query_nldi(url, query_params, error_message):
@@ -79,19 +80,14 @@ def get_flowlines(
         ...     comid=13294314, navigation_mode="UM"
         ... )
     """
-    # validate the navigation mode
-    _validate_navigation_mode(navigation_mode)
-    # validate the feature source and comid
+    navigation_mode = _validate_navigation_mode(navigation_mode)
     _validate_feature_source_comid(feature_source, feature_id, comid)
     if feature_source:
-        # validate the feature source
         _validate_data_source(feature_source)
-
         url = f"{NLDI_API_BASE_URL}/{feature_source}/{feature_id}/navigation"
-        query_params = {"distance": str(distance), "trimStart": str(trim_start).lower()}
     else:
         url = f"{NLDI_API_BASE_URL}/comid/{comid}/navigation"
-        query_params = {"distance": str(distance)}
+    query_params = {"distance": str(distance), "trimStart": str(trim_start).lower()}
 
     url += f"/{navigation_mode}/flowlines"
     if stop_comid is not None:
@@ -232,43 +228,35 @@ def get_features(
         >>> gdf = dataretrieval.nldi.get_features(lat=43.073051, long=-89.401230)
     """
 
-    # check only one origin is provided
-    if (lat and long is None) or (long and lat is None):
+    if (lat is None) != (long is None):
         raise ValueError("Both lat and long are required")
 
-    if lat:
-        if comid:
+    if lat is not None:
+        if comid is not None:
             raise ValueError(
                 "Provide only one origin type - comid cannot be provided"
                 " with lat or long"
             )
-        if feature_source or feature_id:
+        if feature_source is not None or feature_id is not None:
             raise ValueError(
                 "Provide only one origin type - feature_source and feature_id cannot"
                 " be provided with lat or long"
             )
-
-    if not lat:
-        if (comid or data_source) and navigation_mode is None:
+        url = f"{NLDI_API_BASE_URL}/comid/position"
+        query_params = {"coords": f"POINT({long} {lat})"}
+        err_msg = f"Error getting features for lat '{lat}' and long '{long}'"
+    else:
+        if (comid is not None or data_source is not None) and navigation_mode is None:
             raise ValueError(
                 "navigation_mode is required if comid or data_source is provided"
             )
-        # validate the feature source and comid
         _validate_feature_source_comid(feature_source, feature_id, comid)
-        # validate the data source
-        if data_source:
+        if data_source is not None:
             _validate_data_source(data_source)
-        # validate feature source
-        _validate_data_source(feature_source)
-        # validate the navigation mode
-        if navigation_mode:
-            _validate_navigation_mode(navigation_mode)
-
-    if lat:
-        url = f"{NLDI_API_BASE_URL}/comid/position"
-        query_params = {"coords": f"POINT({long} {lat})"}
-    else:
+        if feature_source is not None:
+            _validate_data_source(feature_source)
         if navigation_mode:
+            navigation_mode = _validate_navigation_mode(navigation_mode)
             if feature_source:
                 url = f"{NLDI_API_BASE_URL}/{feature_source}/{feature_id}/navigation"
             else:
@@ -280,19 +268,7 @@ def get_features(
         else:
             url = f"{NLDI_API_BASE_URL}/{feature_source}/{feature_id}"
             query_params = {}
-
-    if lat:
-        err_msg = f"Error getting features for lat '{lat}' and long '{long}'"
-    elif feature_source:
-        err_msg = (
-            f"Error getting features for feature source '{feature_source}'"
-            f" and feature_id '{feature_id}, and data source '{data_source}'"
-        )
-    else:
-        err_msg = (
-            f"Error getting features for comid '{comid}'"
-            f" and data source '{data_source}'"
-        )
+        err_msg = _features_err_msg(feature_source, feature_id, comid, data_source)
 
     feature_collection = _query_nldi(url, query_params, err_msg)
     if as_json:
@@ -413,28 +389,26 @@ def search(
         ... )
 
     """
-    if (lat and long is None) or (long and lat is None):
+    if (lat is None) != (long is None):
         raise ValueError("Both lat and long are required")
 
-    # validate find
     find = find.lower()
     if find not in ("basin", "flowlines", "features"):
         raise ValueError(
             f"Invalid value for find: {find} - allowed values are:"
             f" 'basin', 'flowlines', or 'features'"
         )
-    if lat and find != "features":
+    if lat is not None and find != "features":
         raise ValueError(
             f"Invalid value for find: {find} - lat/long is to get features not {find}"
         )
-    if comid and find == "basin":
+    if comid is not None and find == "basin":
         raise ValueError(
             "Invalid value for find: basin - comid is to get features"
             " or flowlines not basin"
         )
 
-    if lat:
-        # get features by hydrologic location
+    if lat is not None:
         return get_features(lat=lat, long=long, as_json=True)
 
     if find == "basin":
@@ -443,6 +417,11 @@ def search(
         )
 
     if find == "flowlines":
+        if navigation_mode is None:
+            raise ValueError(
+                "navigation_mode is required for find='flowlines';"
+                f" allowed values are {_VALID_NAVIGATION_MODES}"
+            )
         return get_flowlines(
             navigation_mode=navigation_mode,
             distance=distance,
@@ -475,18 +454,36 @@ def _validate_data_source(data_source: str):
             url, {}, "Error getting available data sources"
         )
         _AVAILABLE_DATA_SOURCES = [ds["source"] for ds in available_data_sources]
-        if data_source not in _AVAILABLE_DATA_SOURCES:
-            err_msg = (
-                f"Invalid data source '{data_source}'."
-                f" Available data sources are: {_AVAILABLE_DATA_SOURCES}"
-            )
-            raise ValueError(err_msg)
+
+    if data_source not in _AVAILABLE_DATA_SOURCES:
+        err_msg = (
+            f"Invalid data source '{data_source}'."
+            f" Available data sources are: {_AVAILABLE_DATA_SOURCES}"
+        )
+        raise ValueError(err_msg)
 
 
-def _validate_navigation_mode(navigation_mode: str):
-    navigation_mode = navigation_mode.upper()
-    if navigation_mode not in ("UM", "DM", "UT", "DD"):
-        raise TypeError(f"Invalid navigation mode '{navigation_mode}'")
+def _features_err_msg(feature_source, feature_id, comid, data_source) -> str:
+    if feature_source is not None:
+        return (
+            f"Error getting features for feature source '{feature_source}'"
+            f" and feature_id '{feature_id}', and data source '{data_source}'"
+        )
+    return f"Error getting features for comid '{comid}' and data source '{data_source}'"
+
+
+def _validate_navigation_mode(navigation_mode: str | None) -> str:
+    if navigation_mode is None:
+        raise ValueError(
+            f"navigation_mode is required; allowed values are {_VALID_NAVIGATION_MODES}"
+        )
+    normalized = navigation_mode.upper()
+    if normalized not in _VALID_NAVIGATION_MODES:
+        raise ValueError(
+            f"Invalid navigation mode '{navigation_mode}';"
+            f" allowed values are {_VALID_NAVIGATION_MODES}"
+        )
+    return normalized
 
 
 def _validate_feature_source_comid(

dataretrieval/waterdata/__init__.py

@@ -25,6 +25,8 @@
     get_stats_por,
     get_time_series_metadata,
 )
+from .filters import FILTER_LANG
+from .nearest import get_nearest_continuous
 from .types import (
     CODE_SERVICES,
     PROFILE_LOOKUP,
@@ -34,6 +36,7 @@
 
 __all__ = [
     "CODE_SERVICES",
+    "FILTER_LANG",
     "PROFILES",
     "PROFILE_LOOKUP",
     "SERVICES",
@@ -45,6 +48,7 @@
     "get_latest_continuous",
     "get_latest_daily",
     "get_monitoring_locations",
+    "get_nearest_continuous",
     "get_reference_table",
     "get_samples",
     "get_stats_date_range",