From b0abf4cf6d53bc2b672611b1b973af4d5d7c3555 Mon Sep 17 00:00:00 2001 From: JonyIvy Date: Fri, 10 Nov 2023 16:25:01 +0100 Subject: [PATCH] Doc: update and extend history api docs and examples (#36) --- README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 62 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a205989..85e91a3 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,13 @@ This is a [Signal K Server](https://github.com/SignalK/signalk-server) plugin th This is a total rewrite of [signalk-to-influxdb](https://www.npmjs.com/package/signalk-to-influxdb) that works with InfluxDB v1.x databases. +Once the data is in InfluxDb you can use for example [Grafana](http://grafana.org/) to draw pretty graphs of your data. + Main features: - writes `navigation.position` shaped to work with InfluxDB's [geo features](https://docs.influxdata.com/influxdb/v2.1/query-data/flux/geo/) - supports multiple InfluxDb connections -See [backlog](https://github.com/users/tkurki/projects/1/views/1) for planned features and [Releases](https://github.com/tkurki/signalk-to-influxdb2/releases/tag/v0.0.6) for published features. +See [backlog](https://github.com/users/tkurki/projects/1/views/1) for planned features and [Releases](https://github.com/tkurki/signalk-to-influxdb2/releases) for published features. Discussion in [Signal K Slack](https://signalk-dev.slack.com/) ([get invited](http://slack-invite.signalk.org/)). @@ -21,6 +23,62 @@ Discussion in [Signal K Slack](https://signalk-dev.slack.com/) ([get invited](ht # History API -The plugin implements the Signal K History API, allowing retrieval of historical data with urls like -- http://localhost:3000/signalk/v1/history/values?from=2023-04-23T18:51:26Z&to=2023-04-23T19:58:43Z&paths=environment.wind.angleApparent:min -- http://localhost:3000/signalk/v1/history/values?from=2023-04-23T18:53:20Z&to=2023-04-23T18:55:00Z&paths=environment.wind.angleApparent:min,navigation.speedOverGround:max&resolution=40 +The plugin implements the Signal K History API, allowing retrieval of historical data with HTTP GET requests. + +## Retrieve logged data + +To retrieve logged data from the database, send a request to the `values` endpoint, specifying at least the time interval and SignalK path(s). + +`http://localhost:3000/signalk/v1/history/values?from=2023-04-23T18:53:20Z&to=2023-04-23T18:55:00Z&paths=environment.wind.speedApparent` + +The data returned is in SI units, e.g. vessel and wind speeds in meters/s, angles in radian. + +For further refinement of the queries, you can use the following request parameters. + +### Request Parameters + +The following request parameters are supported in queries: + +* `from` / `to` (mandatory) + + Start and end timestamp, GMT based, e.g. 2023-11-12T21:34:00Z + +* `paths` (mandatory) + + SignalK paths to retrieve, comma-separated. Note that `navigation.position` can not be combined with other paths. + By default the mean value is returned, but a path can be appended with :min or :max to select the minimum or maximum value. + +* `resolution` (optional) + + The time interval in seconds between each point returned. For example `http://localhost:3000/signalk/v1/history/values?paths=navigation.position&from=2023-11-06T17:30:47Z&to=2023-11-12T21:34:00Z&resolution=60` will return the data with one position per minute. The data is simply sampled with InfluxDB's `first()` function. + +* `format` (optional) + + Position data ('navigation.position') can be exported as JSON (default) or in [GPX](https://www.topografix.com/gpx.asp) format. Set `format=gpx` to receive a GPX track. + +### Examples + +Get minimum apparent wind angles: + +`http://localhost:3000/signalk/v1/history/values?from=2023-04-23T18:51:26Z&to=2023-04-23T19:58:43Z&paths=environment.wind.angleApparent:min` + +Get wind angle and boat speed: + +`http://localhost:3000/signalk/v1/history/values?from=2023-04-23T18:53:20Z&to=2023-04-23T18:55:00Z&paths=environment.wind.angleApparent,navigation.speedThroughWater&resolution=60` + +Get the track with positions at intervals of 5 minutes in GPX format: + +`http://localhost:3000/signalk/v1/history/values?from=2023-11-04T10:00:00Z&to=2023-11-12T18:00:00Z&paths=navigation.position&resolution=300` + +## List available data paths + +To retrieve a list of available paths, send a request to the `paths` endpoint with from and to timestamps: + +`http://localhost:3000/signalk/v1/history/paths?from=2023-11-04T00:00:00Z&to=2029-11-25T23:59:59Z` + + +## List available contexts + +To retrieve a list of available contexts, send a request to the `contexts` endpoint with from and to timestamps: + +`http://localhost:3000/signalk/v1/history/contexts?from=2023-11-04T00:00:00Z&to=2029-11-25T23:59:59Z`