History API: return values split by source

[macjl]

History API: return values split by source

The History API now supports filtering by sourceRef via path|sourceRef (#2737), which is useful when the client already knows the source.

What is still missing is a provider-agnostic way to discover/use historical sources when the client does not know them yet.

Example:

GET /signalk/v2/api/history/values?paths=navigation.headingMagnetic&from=...&to=...&splitBySource=true

Expected: return one series per historical source, using the existing values[].sourceRef field:

{
  "values": [
    {
      "path": "navigation.headingMagnetic",
      "method": "average",
      "sourceRef": "can0.c03382007cfd1670"
    },
    {
      "path": "navigation.headingMagnetic",
      "method": "average",
      "sourceRef": "can0.c050a008e8331bf1"
    }
  ],
  "data": [
    ["2026-06-16T21:32:00Z", 1.5289, 1.7188]
  ]
}

Use case: calibration tools need to select and compare specific historical sources without depending on the underlying history provider.

This would complement #2737: filtering works once a source is known; splitBySource=true would allow clients to discover/use source-separated historical values through the History API itself.

[tkurki]

GMTA - after merging 2737 I realised something similar - how would one build a UI that allows the user to pick the sources they want? Or "give me all, but split by source".

Would noValue=true make sense? To just get the sources that have some data for a time period, without getting the values.

If resolution is not specified the server should provide data in a reasonable time resolution, depending on the time range in the request

Would not get you just a single row of values, but using some provider specific time resolution. Or did you mean that with splitBySource but no resolution the result should be one row? Seems tricky.

[macjl]

Yes, I think there are two related use cases:

1. Source discovery for UI:
   /history/values?...&splitBySource=true&noValue=true
   would be enough to build a source picker. Ideally the response would include path, sourceRef, and maybe sampleCount / first / last when available, but no actual values.

2. Source-separated values:
   /history/values?...&splitBySource=true&resolution=30
   would return the normal time series, but split by (path, sourceRef).

I would not expect splitBySource without resolution to mean “one row”. It can keep the current behavior where the server/provider chooses a reasonable resolution. For source discovery, noValue=true avoids that ambiguity.