Skip to content

feat: add radius parameter for spatial filtering for history api and expanded response api spatial queries using history api v2 style #2437

Open
motamman wants to merge 2 commits intoSignalK:masterfrom
motamman:v2-history-api-extensions
Open

feat: add radius parameter for spatial filtering for history api and expanded response api spatial queries using history api v2 style #2437
motamman wants to merge 2 commits intoSignalK:masterfrom
motamman:v2-history-api-extensions

Conversation

@motamman
Copy link
Contributor

Summary

Extends the V2 History API with spatial filtering and enhanced path expressions, and adds a radius query parameter to the Resources API for cross-API consistency.

History API extensions

  • Spatial filtering: New bbox, radius, distance, and position query parameters on /history/values. Supports two equivalent styles for radius queries — the compact radius=lon, lat, meters form and the Resources API-compatible distance=meters&position=[lon,lat] form. Mutually exclusive parameter combinations are validated and return HTTP 400.
  • context parameter: Allows querying historical data for a specific vessel or object (e.g. context=vessels.urn:mrn:imo:mmsi:123456789), defaulting to vessels.self.
  • 4-segment path expressions: New path:aggregate:smoothing:param syntax for post-aggregation smoothing (e.g. navigation.speedOverGround:average:sma:5 computes bucket averages then applies a 5-sample Simple Moving Average). Supports sma and ema smoothing methods.
  • Updated ValuesRequest type: PathSpec gains an optional smoothing field; ValuesRequest gains optional bbox and radius fields so providers receive structured, validated spatial data.

Resources API

  • New radius query parameter: Added RadiusParam to the OpenAPI spec and referenced in all four resource collection GET endpoints (routes, waypoints, regions, notes). The built-in resources provider's processParameters() parses radius=lon,lat,meters into the same geobounds polygon used by bbox and distance+position.

Tests

  • 16 unit tests for splitPathExpression and parseValuesQuery covering all path expression formats, spatial parameter parsing, mutual exclusivity validation, and error cases.
  • Integration test for radius filtering on the Resources API, mirroring the existing bbox test.

Documentation

  • History API docs: expanded query parameter table, new sections on path expressions and spatial filtering with examples.
  • Resources API docs: added radius example alongside existing bbox and distance examples.

Test plan

  • npm run build compiles cleanly
  • npm test — all existing and new tests pass
  • radius query on resources returns the same results as the equivalent bbox query
  • Mutual exclusivity validated (bbox + radius, radius + distance/position)

…expanded spatial queries using hsitory api v2 style
@motamman motamman marked this pull request as ready for review March 12, 2026 02:00
@motamman motamman marked this pull request as draft March 12, 2026 02:01
@motamman motamman marked this pull request as ready for review March 12, 2026 02:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant