From c5c8243ea52cd5d306add7c65f5c27268cba13b3 Mon Sep 17 00:00:00 2001 From: Michael <35783820+mib1185@users.noreply.github.com> Date: Tue, 22 Apr 2025 08:23:17 +0200 Subject: [PATCH] Improve Tankerkoenig docs (#38662) * improve docs * add missing option * Apply suggestions from code review * tiny style tweaks --------- Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> --- source/_integrations/tankerkoenig.markdown | 82 +++++++++++++++++++++- 1 file changed, 79 insertions(+), 3 deletions(-) diff --git a/source/_integrations/tankerkoenig.markdown b/source/_integrations/tankerkoenig.markdown index 8c3a7c2709e..aa56b2e7f89 100755 --- a/source/_integrations/tankerkoenig.markdown +++ b/source/_integrations/tankerkoenig.markdown @@ -16,14 +16,90 @@ ha_platforms: - diagnostics - sensor ha_config_flow: true +related: + - docs: /common-tasks/general/#defining-a-custom-polling-interval + title: Defining a custom polling interval ha_integration_type: integration --- -The `tankerkoenig` platform allows you to monitor the fuel prices with [tankerkoenig.de](https://www.tankerkoenig.de/) from within Home Assistant and setup automations based on the information. -To use this sensor you need an API key from tankerkoenig. Go to [tankerkoenig API](https://creativecommons.tankerkoenig.de) and click on API-KEY in the top right, fill out the form and request a key. The API is free, but requests should be limited to less than once every 5 minutes. +The `tankerkoenig` integration allows you to monitor the fuel prices with [tankerkoenig.de](https://www.tankerkoenig.de/) from within Home Assistant and setup automations based on the information. -{% include integrations/config_flow.md %} +## Prerequisites + +To use this integration, you need an API key from tankerkoenig. +1. Go to [tankerkoenig API](https://creativecommons.tankerkoenig.de) and in the top right, select **API-KEY**. +2. Fill out the form and request a free API key. {% important %} The Terms & Conditions of tankerkoenig.de specify that the API is not meant for massive data fetching, but it does not explicitly mention a limit. Having a maximum of 10 monitored fuel stations is recommended, and a warning will be issued otherwise. +If you consider to [define a custom polling interval](/common-tasks/general/#defining-a-custom-polling-interval), then please keep in mind that requests should be limited to less than once every 5 minutes. {% endimportant %} + +{% include integrations/config_flow.md %} + +{% configuration_basic %} +Region name: + description: "The name of the particular region to be added." +API Key: + description: "The tankerkoenig API-KEY to be used (_see [Prerequisites](#prerequisites)_)." +Location: + description: "Pick the location where to search for gas stations (_defaults to the location of your Home which was et during [onboarding](/getting-started/onboarding)_)" +Search radius: + description: "The radius in kilometers to search for gas stations around the selected location (_default: 2km_)" +Stations: + description: "Select the gas stations you want to add to Home Assistant." +{% endconfiguration_basic %} + +{% include integrations/option_flow.md %} + +{% configuration_basic %} +Stations: + description: "Select the gas stations you want to add to Home Assistant." +Show stations on map: + description: "Weather to show the station sensors on the map or not." +{% endconfiguration_basic %} + +## Data updates + +This integration fetches the data every 30 minutes from the [tankerkoenig API](https://creativecommons.tankerkoenig.de). + +## Provides entities + +This integrations provides a set of {% term "Binary sensor" %} and {% term Sensor %} entities for each selected gas station. + +| Sensors | Description | +| --- | --- | +| Status | Indicates if the gas station is opened or closed at the moment. | +| Diesel | The current price of Diesel fuel. | +| Super | The current price of Super fuel. | +| Super E10 | The current price of Super E10 fuel. | + +{% note %} +As the data of [tankerkoenig.de](https://www.tankerkoenig.de/) is based on data from the German market transparency office for fuels (_[Markttransparenzstelle für Kraftstoffe](https://www.bundeskartellamt.de/DE/Aufgaben/MarkttransparenzstelleFuerKraftstoffe/MTS-K_Infotext/mts-k_node.html) MTS-K_), only the three base fuel types `Diesel`, `Super`, and `Super E10` are available. +{% endnote %} + +## Usage examples + +### Show current fuel price only when station is opened + +The example below uses the common [sensor card](/dashboards/sensor/) in the {% term frontend %} and adds a visibility condition. + +```yaml +graph: line +type: sensor +entity: sensor.my_favorite_gas_station_super +detail: 1 +name: Favorite Gas Station +visibility: + - condition: state + entity: binary_sensor.my_favorite_gas_station_status + state: "on" +``` + +## Troubleshooting + +Before reporting an issue, enable [debug logging](/docs/configuration/troubleshooting/#debug-logs-and-diagnostics) and restart the integration. As soon as the issue re-occurs, stop the debug logging again (_download of debug log file will start automatically_). Further, _if still possible_, download the {% term diagnostics %} data. If you have collected the debug log and the diagnostics data, include them in the issue report. + +## Remove the integration + +{% include integrations/remove_device_service.md %}