Zum Hauptinhalt springen

Tankerkönig Smart-Home-Integration, kostenlos und Open Source

Tankerkönig-Integration für Gladys Assistant

Unofficial connector: German fuel prices per station, cheapest nearby and price alerts.

Auf GitHub ansehenAlle externen Integrationen
Info

Die Dokumentation dieser Integration wird von ihrem Autor geschrieben und ist bisher nur auf Englisch verfügbar.

Unofficial connector, not affiliated with Tankerkönig. It brings the fuel prices of Germany into Gladys through the Tankerkönig open data API: every German station must report its Super E5, Super E10 and Diesel prices to the Markttransparenzstelle für Kraftstoffe (MTS-K), and Tankerkönig republishes them under the CC BY 4.0 licence. Data: Tankerkönig / MTS-K, CC BY 4.0 (tankerkoenig.de).

What you get​

SurfaceContent
One device per watched stationthe price of each tracked fuel the station sells (€ per litre) and whether it is open
The Cheapest nearby deviceper fuel, the lowest price among the open watched stations and the name of the station
Scene triggersfuel price below a threshold (1.40 to 2.20 €/L), fuel price dropped (2 to 10 cents), cheapest station changed, station opened or closed
Scene actioncheapest station nearby: name, brand, address, price and distance of the cheapest open station around the house, for a fuel
Dashboard widgetFuel prices: the cheapest price per fuel, the watched stations with their prices (the cheapest in green), the attribution of the data

Setup​

  1. Request a free personal API key on onboarding.tankerkoenig.de (one key per person; Tankerkönig asks you never to request a second one without contacting them first).
  2. Paste it in Tankerkönig API key, pick the fuels to track and the radius around the house (5 km by default, 25 km at most), then save.
  3. Open Discovery: the stations within the radius of your house (the house position in Gladys, 25 nearest at most) and the Cheapest nearby device are offered. Add the ones you use.
  4. A station further away: the Search stations button lists the stations around the house whose name, brand, street, town or postcode contains a text, with their id. Type the ids in Other stations, separated by commas, with an optional custom name after a colon (278130b1-e062-4a0f-80cc-19e486b4c024:Aral near work), save, and open Discovery again.
  5. Put the Fuel prices widget on a dashboard; its setting shows a single fuel when you pick one.

How often Tankerkönig is called​

Tankerkönig limits its free API to one request per minute ("die Abfragefrequenz auf einen requet/Minute beschränkt", sic) and asks to avoid the regular requests the user did not ask for ("Regelmäßige, nicht explizit vom User initiierte Requests sind zu vermeiden"). So:

  • the prices of the watched stations are read every 10 minutes (option Refresh interval, 5 minutes at least), 10 stations per request, a few random seconds off the round times, and never a station twice within 5 minutes;
  • what nobody asked for right now (that loop, the reading at startup or after a reconnection, the Discovery list prepared at startup) leaves at least one minute after the previous request: with 25 stations, the three requests of a refresh take two minutes;
  • what you ask for (opening Discovery, the Test and Search buttons, a scene running the action) only waits 2 seconds, and reuses the answers already known: a radius search 5 minutes, a station's details a day;
  • a station added in Discovery is read with the next free slot, within about a minute.

Prices, units and closed stations​

  • A price is in euros per litre with three decimals (1.739). Gladys has no "per litre" unit: the features use the euro unit and say "€/L" in their name.
  • The Open feature is 1 when the station is open, 0 when it is closed.
  • A closed station reports no price: its features keep the last known price. The Cheapest nearby device only counts the open stations; when they are all closed, its station name shows "—" and its price stays.
  • A fuel the station does not sell gets no feature.

Scenes​

  • Fuel price below a threshold: pick the fuel, the threshold and the station; the scene runs when the price goes below it, once, not at every refresh. The station is either one watched station or Cheapest nearby, which stands for any watched station: the scene then runs once, when the lowest price among them goes below, whichever station holds it. Variables: the station, the fuel, the price and the previous price.
  • Fuel price dropped: the price fell by at least 2, 3, 5 or 10 cents between two readings, at the chosen station or, with Cheapest nearby, for the lowest price among the watched stations.
  • Cheapest station changed: another watched station now has the lowest open price for a fuel. Adding or removing a station does not count.
  • Station opened or closed: as reported to the MTS-K.

The action cheapest station nearby runs a radius search around the house (the configured radius, or the one you give) and returns {{name}}, {{brand}}, {{address}}, {{price}}, {{distance}} and {{found}} for a message or a condition. Searches are kept 5 minutes, so a scene that runs often does not hammer Tankerkönig.

Troubleshooting​

  • "Tankerkönig refused the API key": the key is wrong or disabled. Tankerkönig asks clients to stop sending requests after such an error: the integration does, until you save the configuration again (with the corrected key, or once Tankerkönig re-enabled it). The Test the API key button checks it with a single request.
  • No station in Discovery: set the position of your house in Gladys (Settings → Houses), check the radius, and remember that the data only covers Germany.
  • "Tankerkönig is unreachable": the service is run by volunteers; the integration keeps trying at every refresh.
  • Logs: the integration's log level is set with the LOG_LEVEL variable. The API key never appears in them.

Data and licence​

The prices and station data come from the Markttransparenzstelle für Kraftstoffe through Tankerkönig, under the CC BY 4.0 licence; the widget shows the attribution "Tankerkönig / MTS-K (CC BY 4.0)". Tankerkönig does not allow oil companies and fuel stations to use its API.

Privacy​

The API key is only sent to Tankerkönig. The radius searches (Discovery, the scene action, the Search button) send Tankerkönig the house position rounded to about 100 m; the price readings only send station ids.

Konfigurationseinstellungen​

Diese Einstellungen fragt Tankerkönig in seinem Konfigurationsbildschirm in Gladys ab.

EinstellungTypPflichtfeldBeschreibung
Fuel prices in GermanysectionNeinUnofficial connector, not affiliated with Tankerkönig. It reads the Tankerkönig open data API (the prices every German station reports to the MTS-K, licensed CC BY 4.0): one device per watched station with its Super E5, Super E10 and Diesel prices and whether it is open, a "Cheapest nearby" device, scene triggers when a price goes below a threshold, drops, or the cheapest station changes, a scene action and a widget. Request a free personal API key (link below) and paste it here: the stations around your house are then suggested in Discovery.
Tankerkönig API keysecretJaStored encrypted by Gladys and only sent to creativecommons.tankerkoenig.de.
Fuels to trackmulti_selectNeinOne price feature per fuel on each station (when the station sells it). None checked: all three.
Radius around the house (km)numberNeinThe stations within this distance are suggested in Discovery (25 nearest at most), and the "Cheapest station nearby" action searches there by default. Tankerkönig allows 25 km at most.
Other stations (ids)stringNeinTankerkönig station ids, separated by commas, with an optional custom name after : — the "Search stations" button gives the ids.
Refresh interval (min)numberNeinHow often the prices of the watched stations are read (10 per request). Tankerkönig asks home automation for 5 minutes at least.

So installierst du Tankerkönig in Gladys​

  1. Öffne in Gladys Integrationen: Tankerkönig erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
  2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/lm1lc3n7/gladys-tankerkoenig:0.1.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
  3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
  4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/LM1LC3N7/gladys-tankerkoenig.

Tankerkönig benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen​

Tankerkönig ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von LM1LC3N7 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂
Zuletzt aktualisiert am