Add read_waterdata_nearest_continuous helper

[thodson-usgs]

Summary

Adds read_waterdata_nearest_continuous(targets, ...) — for each target timestamp, returns the single continuous observation closest to that timestamp, fetched in one HTTP round-trip (auto-chunked when the CQL filter gets long).

Try it

Copy-paste into an R session — installs this branch and runs one end-to-end call:

remotes::install_github(
  "thodson-usgs/dataRetrieval-1",
  ref = "feat/nearest-continuous"
)

library(dataRetrieval)

targets <- as.POSIXct(
  c("2023-06-15 10:30:31", "2023-06-15 14:07:12", "2023-06-16 03:45:19"),
  tz = "UTC"
)

near <- read_waterdata_nearest_continuous(
  targets = targets,
  monitoring_location_id = "USGS-02238500",
  parameter_code = "00060"
)
near[, c("monitoring_location_id", "time", "value", "target_time")]
#> # A tibble: 3 × 4
#>   monitoring_location_id time                value target_time
#>   <chr>                  <dttm>              <dbl> <dttm>
#> 1 USGS-02238500          2023-06-15 10:30:00  22.4 2023-06-15 10:30:31
#> 2 USGS-02238500          2023-06-15 14:00:00  22.4 2023-06-15 14:07:12
#> 3 USGS-02238500          2023-06-16 03:45:00  22.4 2023-06-16 03:45:19

One HTTP request goes out, carrying a three-clause (time >= t-window AND time <= t+window) OR ... CQL filter; three rows come back, one per target. Each time is the nearest observation on the 15-minute grid; target_time identifies which target the row corresponds to.

(No API_USGS_PAT needed to run the snippet — the Water Data API serves unauthenticated requests at a lower rate limit. Set it if you're iterating.)

Tie-mode and wider-window variations:

# Widen the window and average numeric columns for targets that fall
# on the midpoint between two grid observations.
read_waterdata_nearest_continuous(
  targets = targets,
  monitoring_location_id = "USGS-02238500",
  parameter_code = "00060",
  window = "PT15M",      # or "15:00", or "15 minutes"
  on_tie = "mean"
)

Why

The Water Data API's time= parameter treats a single instant as an exact match, not a nearest-match — time = "2023-06-15T10:30:31Z" on a 15-minute gauge returns 0 rows. The advertised sortby parameter would make "nearest" expressible as filter = "time <= 'target'" + sortby = -time + limit = 1, but sortby is per-query, so N targets would mean N HTTP round-trips. There is no T_NEAREST CQL function either.

The narrow-window + client-side reduction implemented here is the one pattern that folds N targets into a single request today.

Knobs

• window = "PT7M30S" — half-window around each target (7.5 minutes, ISO 8601; half of the 15-minute continuous cadence, so most windows contain exactly one observation). Accepts:
  • ISO 8601 durations ("PT7M30S", "PT15M", "PT1H", ...) or any other string lubridate::duration() parses (e.g. "7 minutes 30 seconds")
  • "MM:SS" or "HH:MM:SS" clock-style strings (e.g. "07:30", "15:00", "00:30:00", "01:00:00")
  • for programmatic callers: a number of seconds, a difftime, or a lubridate::Period/Duration
• on_tie = "first" — how to resolve ties when a target falls at the midpoint between two grid points (rare but possible). Alternatives: "last" (keep the later observation), "mean" (average numeric columns; set time to the target).

Multi-site calls return one row per (target, monitoring_location_id) pair. Targets with no observations in their window are silently dropped. Passing time, filter, or filter_lang raises an error — the helper builds those itself.

Naming

Renamed from the Python get_nearest_continuous to read_waterdata_nearest_continuous to match the R package's convention (read_waterdata_* for OGC-backed functions).

Relationship to #880

This PR is built on top of #880 (Add CQL filter passthrough to OGC waterdata functions) and will look lighter once that lands. The helper's core trick — fanning N targets into one request — is only possible because #880 adds filter / filter_lang support + automatic URL-length-safe chunking to read_waterdata_continuous. The branch feat/nearest-continuous is stacked on feat/cql-filter-passthrough, so until #880 merges the diff here will include both changesets; after #880 merges the commits on its branch become common ancestors and this PR's diff reduces to the one commit introducing read_waterdata_nearest_continuous and its tests.

Please merge #880 first.

Test plan

• Non-network unit tests via with_mocked_bindings — 44/44 pass. Covers filter construction (one bracketed AND clause per target, joined by OR), nearest-observation reduction, all three on_tie modes (first / last / mean), missing-window drop, multi-site fan-out, empty targets, forbidden-kwarg validation, and window input shapes (ISO 8601 like "PT7M30S" / "PT15M" / "PT1H", natural-language strings like "7 minutes 30 seconds", "MM:SS" and "HH:MM:SS" including fractional seconds, numeric seconds, difftime, lubridate::Period).
• R CMD check — 0 errors, 0 warnings, 3 unrelated NOTEs.
• Live end-to-end against USGS-02238500 00060 with three off-grid targets (output shown in the Try it section above). One HTTP request, three rows returned, time snapped to the 15-minute grid, target_time preserved as POSIXct.

Marked as draft pending maintainer review.

🤖 Generated with Claude Code