feat(waterdata): name every column the OGC collections return

Comparing each collection's /schema with its getter's signature found 20
returned columns that were reachable only through **queryables, so the
getter documented neither the column nor the filter:

- get_field_measurements: control_condition, day,
  field_measurements_series_id, measurement_rated, month, reading_type,
  time_of_day, year
- get_peaks: qualifier, time_of_day, value
- get_monitoring_locations: revision_created, revision_modified,
  revision_note
- get_combined_metadata: data_gap_interval, reading_type
- get_time_series_metadata: data_gap_interval, parameter_description
- get_field_measurements_metadata: reading_type
- get_channel: channel_location_direction

Each is now a named parameter, described in the service's own words. day,
month and year take the integer annotation get_peaks already uses. The
monitoring-location attributes every collection accepts as filters but
does not return stay in **queryables. Existing calls send the same
request as before.

Stacked: this commit also carries DOI-USGS#422 (Water Data API v1), DOI-USGS#423
(continuous method_category and the API-version monitor) and DOI-USGS#424 (the
documented-columns monitor), which merge first.

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

Author: thodson-usgs

NEWS.md

@@ -1,3 +1,11 @@
+**09/22/2026:** Twenty columns the Water Data OGC collections return are now named, documented parameters on the getter that returns them; before, they were reachable only through `**queryables`. `get_field_measurements()`: `control_condition`, `day`, `field_measurements_series_id`, `measurement_rated`, `month`, `reading_type`, `time_of_day`, `year`. `get_peaks()`: `qualifier`, `time_of_day`, `value`. `get_monitoring_locations()`: `revision_created`, `revision_modified`, `revision_note`. `get_combined_metadata()`: `data_gap_interval`, `reading_type`. `get_time_series_metadata()`: `data_gap_interval`, `parameter_description`. `get_field_measurements_metadata()`: `reading_type`. `get_channel()`: `channel_location_direction`. Existing calls are unaffected: these names are sent to the service exactly as they were through `**queryables`.
+
+**09/22/2026:** The Water Data OGC getters now request **v1** of the Water Data APIs (`api.waterdata.usgs.gov/ogcapi/v1`), [released September 2026](https://waterdata.usgs.gov/blog/api-v1-release/); v0 stays online until June 2027. **New:** `WaterdataConfiguration(api_version="v0")`, or `api_version = "v0"` in the `[waterdata]` table of the configuration file, pins the version for the transition. It replaces only the version segment of the OGC path; the Samples, Statistics and STAC families are versioned separately and have no v1. **Behavior change:** `waterdata.get_time_series_metadata()` returns `begin` and `end` in UTC with a time zone, and no longer returns `begin_utc`, `end_utc`, `state_name` or `hydrologic_unit_code`. **Deprecation:** passing `begin_utc`, `end_utc`, `state`, `state_name` or `hydrologic_unit_code` to that getter, as a filter or in `properties`, emits a `DeprecationWarning` and sends the call to v0, which serves them until June 2027; the shim may be removed on or after 2027-06-01. Use `begin`, `end`, and `get_combined_metadata()` instead. **Behavior change:** `waterdata.get_field_measurements()` returns `time` as a date rather than a datetime, parsed to a tz-naive midnight timestamp as `get_daily()` already does; the time of day is in `time_of_day`. The `field-measurements-metadata` collection has no `time` field and is unaffected.
+
+**09/22/2026:** New live test: each getter that lists its returned columns in its `properties` docstring (`get_daily`, `get_continuous`, `get_time_series_metadata`) is checked against its collection's schema, so a field USGS adds or removes fails the nightly run instead of leaving the docstring wrong.
+
+**09/22/2026:** `waterdata.get_continuous()` accepts `method_category`, which the `continuous` collection began publishing in September 2026: the RLMS method category code (`STNRD`, `LMTUS`, `EXPER` or `UNKWN`) for the method in effect over an observation's interval. It is returned on every record and is null for time series that have not been categorized. It was already reachable through `**queryables`; it is now a documented parameter. `get_latest_continuous()` is unchanged, because `latest-continuous` does not publish the field.
+
 **09/09/2026:** **Bug fix:** code and identifier columns keep their leading zeros. A bare `pandas.read_csv` infers a zero-padded code as a number, so `waterdata.get_samples()` returned parameter code `00060` as `60` and HUC12 `070700050502` as `70700050502`, and `nwis.get_info()` returned `huc_cd` `02060005` as `2060005`. One rule now decides what a code column is — a name ending in `code`, the RDB abbreviation `_cd`, or a name containing `identifier`, `huc`, or `fips` — and every delimited response is parsed through it: the Samples and WQP CSV readers, `rdb.read_rdb` (which reads the names from the RDB header rather than the caller listing them), and the Water Use CSV pages. **Behavior change:** these columns now hold strings. `waterdata.get_samples()`: `USGSpcode`, `Location_HUCEightDigitCode`, `Location_HUCTwelveDigitCode`, `SampleCollectionMethod_Identifier` (`get_samples_summary()` shares the parse; no column in its current profile was affected). `nwis.get_info()`, `nwis.what_sites()`, and `nwis.get_record(service="site")`: `huc_cd`, `state_cd`, `county_cd`, `district_cd`. A comparison against a number — `df["USGSpcode"] == 60` — or a merge onto a numeric key now matches nothing instead of raising, so compare against the padded string (`== "00060"`) or call `.astype(int)` where the number is what you want. **Behavior change:** a count whose name reads as an identifier is numeric again. WQP's `AlternateLocation_IdentifierCount` has been read as text since 05/31/2026 because "Identifier" appears in its name; a name ending in `count` is now excluded from the rule, so the same column has one dtype in every service that reports it. Measurement columns are unchanged, and the `waterdata` OGC getters and `ngwmn` were never affected: their JSON responses deliver codes as strings and numeric coercion there is limited to a fixed list of measurement columns. **Correction to the 1.2.0 notes:** the same fix was applied to the nine `wqp` getters on 05/31/2026 and never recorded here — `wqp.get_results()` and the `what_*` getters have returned HUCs, parameter codes, and FIPS codes as strings since that release.
 
 **09/01/2026:** **Announcement:** We at USGS Water Data for the Nation want your feedback! Tell us how we're doing by taking our quick [survey](https://usgswaterresources.gov1.qualtrics.com/jfe/form/SV_07gX8G1DeOtVrH8), available through September 2026.

dataretrieval/_configuration_core.py

@@ -11,6 +11,7 @@
 
 import math
 import os
+import re
 import stat
 import sys
 import warnings
@@ -26,11 +27,17 @@
 from dataretrieval.exceptions import ConfigurationError
 
 #: Settings only an adapter can hold, because they name one service. No
-#: package-wide value could mean anything for them: there is no one base URL.
+#: package-wide value could mean anything for them: there is no one base URL,
+#: and a version is a segment of one service's paths.
 #:
 #: The package-wide roster is :data:`SETTINGS`, declared below the class it is
 #: derived from.
-ADAPTER_ONLY_SETTINGS: tuple[str, ...] = ("base_url",)
+ADAPTER_ONLY_SETTINGS: tuple[str, ...] = ("base_url", "api_version")
+
+#: The adapter-only settings the file refuses too, leaving a ``configure()``
+#: block as the only source that can supply one (ADR 0011). Named for the
+#: *source*, the term the chain spells ``_BLOCK`` everywhere else.
+BLOCK_ONLY_SETTINGS: tuple[str, ...] = ("base_url",)
 
 #: Environment variable backing a setting (precedence step 2).
 #:
@@ -52,12 +59,9 @@
 
 #: Variables the environment is *refused* for, by setting. Named rather than left out of
 #: :data:`ENV_VARS`, so a caller who exports ``API_USGS_BASE_URL`` gets an error instead
-#: of an ignored variable. The file refuses the same key in the same words
-#: (:func:`_accepted_keys`): a base URL set outside the code could redirect the library
-#: to another host without a reader of the script seeing it (ADR 0011).
-#:
-#: Derived from :data:`ADAPTER_ONLY_SETTINGS` so the file and the environment
-#: cannot drift apart on which settings are code-only.
+#: of an ignored variable. Derived from :data:`ADAPTER_ONLY_SETTINGS`, because a
+#: variable applies to every adapter and those settings name one. The file
+#: refuses only :data:`BLOCK_ONLY_SETTINGS` (ADR 0011).
 _REFUSED_ENV_VARS: dict[str, str] = {
     name: f"API_USGS_{name.upper()}" for name in ADAPTER_ONLY_SETTINGS
 }
@@ -393,9 +397,7 @@ def _provenance(self) -> str:
 # Plain mixins rather than ``BaseConfiguration`` subclasses: a group has no
 # adapter and cannot be passed to :func:`configure`, so keeping it off that
 # branch leaves one linear base for the behavior. Frozen because a dataclass
-# may not mix frozen and non-frozen bases; fields collect in reverse MRO order,
-# so an adapter composing all four reads ``retries, stall_timeout, base_url,
-# concurrency, parallel_chunks``.
+# may not mix frozen and non-frozen bases. Fields collect in reverse MRO order.
 
 
 @dataclass(frozen=True)
@@ -413,6 +415,13 @@ class _Redirectable:
     base_url: str | None = _UNSET
 
 
+@dataclass(frozen=True)
+class _Versioned:
+    """An adapter whose service publishes its API under a version path segment."""
+
+    api_version: str | None = _UNSET
+
+
 @dataclass(frozen=True)
 class _Concurrent:
     """An adapter that issues more than one request per call."""
@@ -771,6 +780,7 @@ def _coerce_count(value: object, label: str, optional: str) -> str:
 #: so the wider check cannot change a TOML outcome.)
 _TYPES: dict[str, Callable[[object, str, str], str]] = {
     "api_key": _coerce_string,
+    "api_version": _coerce_string,
     "base_url": _coerce_string,
     "progress": _coerce_progress,
     "concurrency": _coerce_concurrency,
@@ -899,6 +909,26 @@ def _parse_base_url(raw: str, label: str) -> str:
     return value
 
 
+#: The one shape a version takes in every Water Data path: ``v`` and digits.
+_API_VERSION_RE = re.compile(r"^v\d+$")
+
+
+def _parse_api_version(raw: str, label: str) -> str:
+    """Parse an API version: the segment the service publishes it under, ``v1``.
+
+    Checked as a shape, not against a list. This module cannot know which
+    versions a service has published, and a closed list here would refuse a
+    version the service already serves until a release of this package named it.
+    """
+    value = raw.strip()
+    if not _API_VERSION_RE.match(value):
+        raise ConfigurationError(
+            f"{label} must be the version segment of the service's path, "
+            f"such as 'v1' (got {raw!r})."
+        )
+    return value
+
+
 def _parse_progress(raw: str, label: str, *, strict: bool) -> bool:
     """Parse a progress toggle, optionally preserving legacy env truthiness."""
     value = raw.strip().lower()
@@ -931,6 +961,7 @@ def _parse_progress(raw: str, label: str, *, strict: bool) -> bool:
     "parallel_chunks": _parse_parallel_chunks,
     "stall_timeout": _parse_seconds,
     "base_url": _parse_base_url,
+    "api_version": _parse_api_version,
 }
 
 
@@ -1048,11 +1079,13 @@ def _adapter_file_settings(
 
     where = f"[{adapter}]"
     # An adapter this process has not imported declares no vocabulary, so its
-    # table is checked against the package-wide settings alone: refusing a key
-    # for want of a schema would make the file's validity depend on which
-    # optional extras happened to be installed.
+    # table is checked against every setting this release has a grammar for:
+    # refusing a key for want of a schema would make the file's validity depend
+    # on which optional extras happened to be installed.
     accepted = settings_for(adapter)
-    validated = _scalars(table, path, where, SETTINGS if accepted is None else accepted)
+    validated = _scalars(
+        table, path, where, _ALL_SETTINGS if accepted is None else accepted
+    )
     label = f"{path} {where}"
     result: Mapping[str, tuple[str, str]] = MappingProxyType(
         {name: (value, label) for name, value in validated.items()}
@@ -1230,7 +1263,7 @@ def _accepted_keys(
             # and :func:`_named_profile` refuses a table inside a profile, so a
             # sub-table here is always a profile rather than deeper nesting.
             continue
-        if key in ADAPTER_ONLY_SETTINGS:
+        if key in BLOCK_ONLY_SETTINGS:
             # Rejected from the file wherever it appears. A file that
             # redirects a data-retrieval library to another host is a
             # supply-chain hazard; an in-code block keeps the redirect
@@ -1240,16 +1273,7 @@ def _accepted_keys(
                 "configure() block, never from a file."
             )
         if key not in allowed:
-            if key in SETTINGS:
-                # A real setting, in a table that does not read it. Unlike an
-                # unrecognized name -- which may belong to a newer release --
-                # this cannot become meaningful later, and ignoring it without an error
-                # would leave a caller believing they had tuned something. See
-                # ADR 0010.
-                raise ConfigurationError(
-                    f"{path}: {key!r} at {where} is not a setting that table "
-                    f"accepts. It accepts: {', '.join(sorted(allowed))}."
-                )
+            _reject_known_setting(key, path, where, allowed)
             warnings.warn(
                 f"{path}: unknown setting {key!r} at {where} (ignored). "
                 f"Known settings: {', '.join(SETTINGS)}.",
@@ -1261,6 +1285,32 @@ def _accepted_keys(
     return out
 
 
+def _reject_known_setting(
+    key: str, path: Path, where: str, allowed: frozenset[str] | tuple[str, ...]
+) -> None:
+    """Raise if *key* is a setting this release knows but that table cannot use.
+
+    Returns for a name this release does not know, which the caller warns about
+    instead: only one of the two can be a typo for a newer release, and a real
+    setting in a table that does not read it cannot become meaningful later --
+    ignoring it without an error would leave a caller believing they had tuned
+    something (ADR 0010).
+    """
+    if where == _TOP_LEVEL and key in ADAPTER_ONLY_SETTINGS:
+        # The generic message below would list only top-level settings, none of
+        # which is the one to write.
+        raise ConfigurationError(
+            f"{path}: {key!r} at {where} names one service and has no "
+            "package-wide value; set it in the table of the adapter it belongs "
+            "to, such as [waterdata]."
+        )
+    if key in _ALL_SETTINGS:
+        raise ConfigurationError(
+            f"{path}: {key!r} at {where} is not a setting that table "
+            f"accepts. It accepts: {', '.join(sorted(allowed))}."
+        )
+
+
 def _checked_table(
     table: dict[str, Any],
     path: Path,

dataretrieval/_deprecation.py

@@ -19,6 +19,10 @@
     "waterdata.get_cql(service=)": "2027-08-09",
     "wateruse": "2027-08-11",
     "ogc.interruptions": "2027-08-25",
+    # Set by the service, not by this package: v0 of the collection serves these
+    # filters until June 2027, and the shim cannot outlive the endpoint it sends
+    # to (https://waterdata.usgs.gov/blog/api-v1-release/).
+    "waterdata.get_time_series_metadata(v0 filters)": "2027-06-01",
 }
 
 

dataretrieval/configuration.py

@@ -72,6 +72,7 @@
 # isort: off
 from dataretrieval._configuration_core import (
     ADAPTERS as ADAPTERS,
+    BLOCK_ONLY_SETTINGS as BLOCK_ONLY_SETTINGS,
     CONFIG_PATH_ENV as CONFIG_PATH_ENV,
     CONCURRENCY_UNBOUNDED as CONCURRENCY_UNBOUNDED,
     DEFAULT_CONCURRENCY as DEFAULT_CONCURRENCY,
@@ -94,6 +95,7 @@
     _Frame as _Frame,
     _named_profiles as _named_profiles,
     _NO_FILE as _NO_FILE,
+    _parse_api_version as _parse_api_version,
     _parse_base_url as _parse_base_url,
     _parse_concurrency as _parse_concurrency,
     _parse_parallel_chunks as _parse_parallel_chunks,
@@ -112,6 +114,7 @@
     _SettingValue as _SettingValue,
     _UNSET as _UNSET,
     _validated_raw as _validated_raw,
+    _Versioned as _Versioned,
     config_path as config_path,
     settings_for as settings_for,
 )
@@ -655,6 +658,45 @@ def base_url(*, adapter: str | None = None, default: str | None = None) -> str |
     return _parse_base_url(raw, label)
 
 
+@overload
+def api_version(*, adapter: str | None = ...) -> str | None: ...
+
+
+@overload
+def api_version(*, adapter: str | None = ..., default: str) -> str: ...
+
+
+def api_version(
+    *, adapter: str | None = None, default: str | None = None
+) -> str | None:
+    """An adapter's configured API version, falling back to *default*.
+
+    Settable from code and from the file: an adapter configuration may include
+    it, and so may that adapter's table. The environment refuses it
+    (:data:`_REFUSED_ENV_VARS`), as it refuses every adapter-only setting -- a
+    variable is package-wide, and a version names one service's paths.
+
+    Like :func:`base_url`, there is no package-wide default: the version an
+    adapter's requests use is the adapter's own, so the service passes its own
+    -- ``api_version(adapter="waterdata", default=OGC_API_VERSION)`` -- and the
+    version stays declared in the module that builds the path.
+
+    Parameters
+    ----------
+    adapter : str, optional
+        Whose version to resolve.
+    default : str, optional
+        The version the service is written against, returned when nothing
+        configured one. Omitted, ``None`` is returned -- which is what
+        :func:`show_configuration` passes, since it has no service default to
+        supply.
+    """
+    raw, label, _source = _resolve("api_version", adapter)
+    if raw is None:
+        return default
+    return _parse_api_version(raw, label)
+
+
 # --- resolution ----------------------------------------------------------
 
 #: Which source of the chain supplied a resolution. Machine-readable so a
@@ -729,16 +771,27 @@ def _check_env_not_refused(name: str) -> None:
     Refused before anything is consulted, not when the chain reaches the environment
     source. The file and the environment refuse ``base_url`` as one rule (ADR 0011), so
     a variable that cannot work is not outranked, with no error, by a block that happens
-    to work.
+    to work. ``api_version`` is refused from the environment alone: the file may
+    set it, in an adapter's table, and the message says so.
     """
     refused = _REFUSED_ENV_VARS.get(name)
-    if refused is not None and refused in os.environ:
-        raise ConfigurationError(
-            f"{_env_label(refused)} is set, but {name!r} may only be set "
-            "in code, in a configure() block, never from the environment. Unset "
-            f"it and pass the value on the adapter's configuration, e.g. "
-            f"WaterdataConfiguration({name}=...)."
-        )
+    if refused is None or refused not in os.environ:
+        return
+    block_only = name in BLOCK_ONLY_SETTINGS
+    fault = (
+        "may only be set in code, in a configure() block, never from the environment"
+        if block_only
+        else "names one service and has no package-wide value, so the environment "
+        "cannot set it"
+    )
+    # The file is a source for everything except the block-only settings, so it
+    # is offered as an alternative to exactly the settings it can supply.
+    or_the_file = "" if block_only else ", or in that adapter's table of the file"
+    raise ConfigurationError(
+        f"{_env_label(refused)} is set, but {name!r} {fault}. Unset it and pass "
+        f"the value on the adapter's configuration, e.g. "
+        f"WaterdataConfiguration({name}=...){or_the_file}."
+    )
 
 
 def _resolve_from_block(
@@ -837,6 +890,7 @@ def _display_progress(_adapter: str | None = None) -> str:
     "parallel_chunks": lambda adapter: str(parallel_chunks(adapter=adapter)),
     "stall_timeout": lambda adapter: f"{stall_timeout(adapter=adapter):g}s",
     "base_url": lambda adapter: base_url(adapter=adapter) or "<service default>",
+    "api_version": lambda adapter: api_version(adapter=adapter) or "<service default>",
 }
 
 if set(_DISPLAYS) != set(_ALL_SETTINGS):  # pragma: no cover - guards a coding error