## Using a History API Provider

Skip reads historical data from an external Signal K History API provider plugin. With a compatible provider installed, Skip can:
1. Pre-seed Data Graph and Wind Trends so they show recent trends immediately.
2. Populate historical views for widgets on your pages that use numeric value paths.

You must configure the provider plugin to capture the paths you want to graph, and it must have enough recorded data to cover your graph time span. This is not automatic.

Running a provider gives you full control, including:
- Long-term record keeping.
- Custom retention and sampling rules.
- Analytics or integration with tools such as Grafana.

## Which Widgets Support History?

Most widgets that use numeric paths support history, including Horizon, Battery Monitor, Solar, and similar numeric-based widgets. Your provider plugin must be configured to capture the paths you want to graph.

## Required Plugins and Signal K Version

You need:
- Signal K support for History API v2 (introduced in Signal K v2.22.1).
- A compatible History API provider plugin.

Currently, two plugins support History API v2:

### 1. signalk-to-influxdb2 (v2.0.0+)
- **Purpose:** Records Signal K data to an InfluxDB v2 time-series database (requires InfluxDB v2).
- **Link:** [signalk-to-influxdb2](https://www.npmjs.com/package/signalk-to-influxdb2)
- **Setup:** Follow the plugin documentation for installation and configuration.
- **Path Configuration:** By default, records all paths. Configure filters, resolution, and related settings for the paths you want available in Skip graphs.

### 2. signalk-parquet
- **Purpose:** Records Signal K data to Parquet files for efficient storage and querying (no external database required).
- **Link:** [signalk-parquet](https://www.npmjs.com/package/signalk-parquet)
- **Setup:** Follow the plugin documentation for installation and configuration.
- **Path Configuration:** You must specify which paths to record; none are recorded by default.

## How History Data Works in Skip

### History Seeding
When you open a graph widget with a larger time scale (minutes/hours):
1. Skip checks whether history data is available through the History API.
2. If available and the time window allows it (resolution >= 1000 ms), Skip requests historical data points.
3. The graph displays the historical trend immediately.

### Live Updates
After history data loads:
- New data points continue to arrive through Signal K's live WebSocket connection.
- The graph transitions smoothly from history to live updates.
- Old points are removed to maintain a rolling window based on the configured time scale.

### When History Is Not Available
- If no History API plugin is installed, the graph widgets show a "History data unavailable" state, and the pop-up history dialog reports that no historical data is available. They do not fall back to live data.
- If a provider is installed but reports that a path is not recorded, history seeding is skipped and the graph shows live data only, starting from when it was opened.
- Neither case indicates an error.

## Provider Plugin Configuration

Skip does not impose a fixed datapoint limit. For each request it derives a resolution (sample interval) from the time window being shown and asks the provider to return data at that resolution:
- The Data Graph targets roughly 500 points across its window (with a floor for very short windows), so finer sampling produces more detail rather than a capped number of points.
- The pop-up history graph dialog targets a lighter density (about 120 points) across its fixed windows.

A graph can only show detail the provider recorded. When configuring provider sampling rates:
- If the provider stored data at a coarser interval than Skip requests, the graph shows that coarser detail (lower visual resolution), whatever the window.
- Recording at a finer interval than Skip requests is fine — Skip asks for the resolution it needs and the provider returns data at that resolution.

### Widget Historical Graphs

For the smallest fixed window (**last 15 minutes**), collect enough samples to provide useful resolution. A sampling interval around 7.5 seconds is ideal; 15 seconds is also usable.

### Wind Trends Fixed Paths

The Wind Trends widget uses two Signal K paths. The **Wind** setting selects which pair:
- **True:** `environment.wind.speedTrue`, with `environment.wind.directionTrue` or `environment.wind.directionMagnetic`, whichever the direction reference selects.
- **Apparent:** `environment.wind.angleApparent` and `environment.wind.speedApparent`. Apparent wind is measured from the bow, so the direction reference does not apply.

To display Wind Trends history, both paths of the selected wind **must be captured by your selected History API plugin**.

Choose a sampling rate that supports graph durations of 5 and 30 minutes.

## Limitations

To seed graphs with historical data, you must configure your provider to collect the required paths. This is not automatic.

## Troubleshooting

### History Data Is Not Showing

**Check 1: Are the technical requirements met?**
- Confirm Signal K server v2.22.1 or later is installed.

**Check 2: Is a History API plugin installed?**
- Confirm a History API plugin is installed and only one provider plugin is enabled.
- Verify the plugin is running without errors (check server logs).

**Check 3: Are paths configured in the plugin?**
- Open plugin configuration.
- Confirm the paths you are graphing (for example, `navigation.speedThroughWater`) are included in the capture list.

**Check 4: Is there historical data available?**
- If the plugin was installed recently, data is only available from that point onward.
- Graphs cannot display history for periods before the plugin was enabled or before the path was configured.
- Allow time for data to accumulate before expecting deeper history.

**Check 5: Is the graph time scale eligible?**
- Very short time scales (seconds) skip history seeding for performance.
- Use graph time scales of **minutes or longer** for history seeding.

**Check 6: Are there network or permission issues?**
- Confirm Skip can reach the Signal K server History API endpoint.
- Use the OpenAPI link in Signal K Server Admin pages to test endpoint availability.
- Check browser console logs (F12) for HTTP errors from history requests.

## Next Steps

1. Verify that a History API plugin is installed on your Signal K server.
2. Configure the plugin to capture the paths you want to graph.
3. Wait for the plugin to collect enough data to fill your graph time span.
4. Open a Data Graph or Wind Trends widget with a time scale of minutes or longer.
5. Let the graph load; history appears when available.
6. For more details, consult plugin documentation and Signal K community resources.

## Questions or Issues?

- Refer to plugin and History API documentation for provider-specific setup and troubleshooting.
- For general questions or issues, see the Contact-Us help page. The Signal K community is active on Discord and GitHub.