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

[thodson-usgs]

TL;DR: Adds named, documented parameters for 20 columns that the Water Data OGC collections return and that could previously be passed only through **queryables; keyword calls send the same request as before. The new parameters are keyword-only, so no existing call changes meaning, including a call that passes arguments by position. The one exception is that two parameters released in 1.4.0 (statistics_begin and method_category) also become keyword-only; see below. The PR also adds a live check that would have found these columns, and a contract test that fails if a getter gains a parameter that can be passed by position.

One commit on current main. #422, #423, #424 and #427 have merged; the duplicate of #424's commit was dropped on rebase.

Changes

Getter	Added
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

• Descriptions are adapted from each collection's /schema. day, month and year are typed int | list[int], as in get_peaks.
• The properties lists of get_monitoring_locations and get_channel add their missing columns.
• get_peaks' qualifier and value docstrings, and parameter_description in get_combined_metadata and get_field_measurements_metadata, use the same wording as the other getters and the service's /schema. The qualifier text now includes the exact, in-order matching rule, which applies to peaks too.

Tests (tests/waterdata_properties_test.py)

One table maps each of the eleven OGC collections to its getter. Three checks use it:

• Offline: every named parameter of each getter reaches the OGC engine. The cases come from the signatures, so a new parameter is covered on the day it is added. This replaces the hand-kept _NEWLY_NAMED list. qualifier's JSON encoding stays covered by test_qualifier_is_sent_as_a_json_array, whose peaks case is renamed from peaks-queryables.
• Live: every column a collection's /schema publishes, other than its id and geometry, is a named parameter of its getter. Run against main, this fails on exactly the 20 columns this PR names.
• Live: the documented column lists match the schema. This now includes get_monitoring_locations and get_channel. The schema's id and the name the getter returns it under (_OUTPUT_ID_BY_COLLECTION) are left out of both sides, and a list ends at the sentence that follows it.

For the maintainer

• Parameter order: the new parameters come after a bare * at the end of each signature, so every parameter released in v1.4.0 keeps its position. They were first inserted before properties, which would have silently rebound a positional properties (the fourth argument of get_field_measurements and get_time_series_metadata) as a filter, the problem fix(waterdata): keep sublocation_identifier from shifting positional arguments #447 fixed for sublocation_identifier. sublocation_identifier, which is unreleased, is now keyword-only too.
  • test_no_parameter_is_added_by_position in tests/contracts/public_api_test.py records how many parameters each Water Data getter accepts by position, and fails if a getter gains one. It would have failed on this PR's earlier layout for all seven getters. The module docstring no longer calls a reorder harmless.
  • Behavior change: statistics_begin (feat(waterdata): request v1 of the Water Data API, pinnable through api_version #422, get_time_series_metadata) and method_category (fix(waterdata): accept the continuous method_category queryable #423, get_continuous) shipped mid-signature in v1.4.0 on 10/02, and are now keyword-only too. That shifts the later positional parameters by one: from thresholds in get_time_series_metadata and from value in get_continuous. A call that passed one of those by position must now pass it by name. The risk is low given the release date, and NEWS marks the change. The recorded counts exclude these two.
  • The order of the older parameters, or making most of them keyword-only, can be revisited in the next major release, with the deprecation notice ADR 0012 requires.
• Not added: the ~240 monitoring-location attributes (county_name, site_type, ...) that every data collection accepts as filters but does not return. They stay in **queryables.
• get_peaks(value=...) is typed as a string, because the service transmits peak values as strings to preserve precision.
• NEWS.md is dated 10/13/2026 and placed on top; set it to the merge date.

Verification

• Offline: 1650 passed. Pre-commit (ruff, mypy, import-linter, complexipy, xenon) passes.
• Live: tests/waterdata_properties_test.py, 18 passed (2026-10-13).
• Live: filtering on a value taken from a response returned only matching rows for measurement_rated, reading_type, control_condition and parameter_description.

🤖 Generated with Claude Code

[ehinman]

I think putting the new input parameters before properties makes sense. Using positional argument orders to pull data is not very robust on the user's part, so I don't see an issue with changing the positions of the arguments, if only to encourage calling out the inputs specifically.

One question, why are all these PRs merging to main as opposed to the switch to v1? There's a lot of redundancy in these PRs. I'll admit I don't quite understand what's going on with the conflicts and what not. I'll re-read the issue #426.

[thodson-usgs]

There's a lot of redundancy in these PRs.

Yes, these build off each other. Is that what you mean?

Simplest to go in order described in issue #426, and work through them one by one. Merging before moving to the next. I'll work through the first couple, then check back in.