Beschreibung
Logikbaustein für aktuelle Spritpreise über die API von Tankerkönig. Er löst den freien Baustein [Tankerkoenig](Tankerkoenig.md) ab. Neu sind mehrere Tankstellen, die günstigste offene Tankstelle und feste Tankstellen (Stammtankstellen).
Für den Betrieb braucht man einen eigenen, kostenlosen API-Key von https://onboarding.tankerkoenig.de. Den Key nicht veröffentlichen.
- Gerät
- Gira HomeServer
- Version
- 0.1.0
- Lizenz
- Ein Schlüssel je HomeServer (MAC-Adresse), dauerhaft nutzbar
- Thema
- Daten aus dem Netz
Hinweis zur Schnittstelle: Der Baustein nutzt die Schnittstelle von tankerkoenig.de. Ändert der Anbieter sie oder stellt sie ein, kann der Baustein eingeschränkt oder gar nicht mehr funktionieren, bis er angepasst ist. Wir passen ihn nach Möglichkeit an, einen Anspruch darauf gibt es nicht.
Anleitung
Besonderheiten beim HomeServer
- Modus, Spritsorte und Sortierung sind Zahlen (siehe Tabelle).
- Einzelausgänge (Name, Preis, Offen, Entfernung) gibt es für die ersten 5 Tankstellen statt 10, alle stehen im Ausgang JSON.
- Die „Bezeichnung Tankstelle i“ sind ein Eingang mit kommagetrennter Liste.
- „Offen“ ist
0/1. HTTPS läuft direkt über Python (urllib2), nicht über curl.
- Statt Parametern gibt es Eingänge mit Startwert. Auswahllisten des X1 sind Zahlen, Ja/Nein-Werte sind
0und1. - Der Lizenzschlüssel ist der letzte Text-Eingang. Ein neuer Wert an diesem Eingang wird sofort geprüft.
- Eine Prüfung des Schlüssels im Editor und eine Simulation gibt es nicht, der HomeServer prüft immer.
Funktionen und Anschlüsse
Logikbaustein von SMoLabs für aktuelle Spritpreise über die API von Tankerkönig (https://creativecommons.tankerkoenig.de). Für den Betrieb braucht man einen eigenen, kostenlosen API-Key von https://onboarding.tankerkoenig.de. Den Key nicht veröffentlichen.
Modus 1 = Umkreissuche (alle Tankstellen im Umkreis, höchstens 25 km), Modus 2 = Feste Tankstellen (bis zu 10 bestimmte Tankstellen über ihre ID, von Tankerkönig für regelmäßige Aktualisierungen empfohlen). Pro Abfrage werden immer alle Sorten (E5, E10, Diesel) geholt. Ein Wechsel der Sorte kostet also keine zusätzliche Abfrage. Die ID einer Tankstelle steht im Ausgang „ID günstigste“ oder im Ausgang „JSON“ einer Umkreissuche.
Abgefragt wird, wenn E1 einen Wert ungleich 0 bekommt. Tankerkönig erlaubt mit der freien API höchstens eine Abfrage pro Minute. Für Hausautomation gilt: höchstens alle 5 Minuten und nicht zu runden Uhrzeiten, z. B. alle 7 Minuten. Bei Missbrauch sperrt Tankerkönig den Key. Ein Trigger innerhalb von 60 Sekunden nach der letzten Abfrage wird ignoriert („Debug“ nennt den Grund).
Fehlerverhalten: Bei Verbindungsproblemen, Fehlermeldungen der API oder HTTP-Fehlern bleiben die Ausgänge auf dem letzten Stand, der Grund steht unter „Debug“. Plätze, für die eine erfolgreiche Abfrage keine Tankstelle mehr liefert, werden zurückgesetzt.
Datenquelle: Markttransparenzstelle für Kraftstoffe (MTS-K) über Tankerkönig, CC BY 4.0. Wer die Preise z. B. in einer Visualisierung zeigt, nennt dort tankerkoenig.de als Quelle.
Eingänge
| Nr. | Name | Init | Bedeutung |
|---|---|---|---|
| 1 | E1 Trigger | 0 | Ungleich 0: startet die Abfrage. |
| 2 | E2 API-Key | „“ | Persönlicher Tankerkönig-Key. |
| 3 | E3 Modus (1 = Umkreissuche, 2 = Feste Tankstellen) | 1 | 1 = Umkreissuche (Vorgabe), 2 = Feste Tankstellen. |
| 4 | E4 Spritsorte (1 = E5, 2 = E10, 3 = Diesel) | 2 | 1 = E5, 2 = E10 (Vorgabe), 3 = Diesel. Gilt für „Günstigster Preis“, „Preis i“ und die Sortierung. |
| 5 | E5 Breitengrad (nur Umkreissuche) | 52.521 | Standort der Umkreissuche. Vorgabe 52.521 (Berlin), unbedingt auf den eigenen Standort ändern. |
| 6 | E6 Längengrad (nur Umkreissuche) | 13.438 | Standort der Umkreissuche. Vorgabe 13.438 (Berlin). |
| 7 | E7 Suchradius in km (nur Umkreissuche, max. 25) | 5 | 0,1 bis 25, Vorgabe 5. |
| 8 | E8 Sortierung (nur Umkreissuche, 1 = Preis, 2 = Entfernung) | 1 | 1 = nach Preis der Spritsorte (Vorgabe, Tankstellen ohne Preis am Ende), 2 = nach Entfernung. |
| 9 | E9 Tankstellen-IDs (nur feste Tankstellen, kommagetrennt, max. 10) | „“ | Bis zu 10 IDs, getrennt durch Komma, Semikolon oder Leerzeichen. |
| 10 | E10 Bezeichnungen (nur feste Tankstellen, kommagetrennt, gleiche Reihenfolge wie die IDs) | „“ | Feste Tankstellen: Namen für die IDs, durch Komma getrennt in derselben Reihenfolge, weil prices.php keine Namen liefert. Leer = ID. |
| 11 | E11 Lizenzschlüssel | „“ | Lizenzschlüssel für diesen HomeServer (von smolabs.de). Ohne gültigen Schlüssel bleibt der Baustein untätig. |
Ausgänge
| Nr. | Name | Init | Bedeutung |
|---|---|---|---|
| 1 | A1 Günstigster Preis | 0 | Preis der Spritsorte in Euro je Liter bei der günstigsten offenen Tankstelle, 0 = keine gefunden. |
| 2 | A2 Name günstigste | „“ | Name der günstigsten Tankstelle. |
| 3 | A3 Marke günstigste | „“ | Marke der günstigsten Tankstelle (bei festen Tankstellen leer). |
| 4 | A4 Adresse günstigste | „“ | Adresse der günstigsten Tankstelle (bei festen Tankstellen leer). |
| 5 | A5 ID günstigste | „“ | ID der günstigsten Tankstelle. |
| 6 | A6 Anzahl offen | 0 | Anzahl der geöffneten Tankstellen in der Liste. |
| 7 | A7 Name 1 | „“ | Name der 1. Tankstelle (Reihenfolge der Sortierung, bei festen Tankstellen die der IDs). |
| 8 | A8 Preis 1 | 0 | Preis der Spritsorte, 0 = Sorte nicht geführt oder kein Preis. |
| 9 | A9 Offen 1 | 0 | 1, wenn geöffnet. |
| 10 | A10 Entfernung 1 in km | 0 | Entfernung in km (nur Umkreissuche, sonst 0). |
| 11 | A11 Name 2 | „“ | Name der 2. Tankstelle. |
| 12 | A12 Preis 2 | 0 | Preis der 2. Tankstelle. |
| 13 | A13 Offen 2 | 0 | 1, wenn geöffnet. |
| 14 | A14 Entfernung 2 in km | 0 | Entfernung in km. |
| 15 | A15 Name 3 | „“ | Name der 3. Tankstelle. |
| 16 | A16 Preis 3 | 0 | Preis der 3. Tankstelle. |
| 17 | A17 Offen 3 | 0 | 1, wenn geöffnet. |
| 18 | A18 Entfernung 3 in km | 0 | Entfernung in km. |
| 19 | A19 Name 4 | „“ | Name der 4. Tankstelle. |
| 20 | A20 Preis 4 | 0 | Preis der 4. Tankstelle. |
| 21 | A21 Offen 4 | 0 | 1, wenn geöffnet. |
| 22 | A22 Entfernung 4 in km | 0 | Entfernung in km. |
| 23 | A23 Name 5 | „“ | Name der 5. Tankstelle. |
| 24 | A24 Preis 5 | 0 | Preis der 5. Tankstelle. |
| 25 | A25 Offen 5 | 0 | 1, wenn geöffnet. |
| 26 | A26 Entfernung 5 in km | 0 | Entfernung in km. |
| 27 | A27 Letzte Abfrage | „“ | Zeit der letzten erfolgreichen Abfrage (deutsche Zeit), TT.MM.JJJJ HH:mm:ss. |
| 28 | A28 JSON | „“ | Alle Tankstellen als JSON-Liste (id, name, marke, adresse, entfernung, offen, e5, e10, diesel, ohne Preis null). |
| 29 | A29 Lizenzstatus | „“ | Ergebnis der Lizenzprüfung, z. B. „Lizenz gültig (2026-000123)“. |
| 30 | A30 Debug | „“ | Ergebnis bzw. Fehler der letzten Abfrage. |
Lizenz
Der Lizenzschlüssel wird am letzten Text-Eingang des Bausteins eingetragen. Der Baustein prüft ihn auf dem HomeServer, offline und gebunden an die MAC-Adresse des HomeServers. Der Ausgang „Lizenzstatus“ zeigt das Ergebnis, bei einem Schlüssel für ein anderes Gerät auch die MAC-Adresse dieses HomeServers. Ohne gültigen Schlüssel bleibt der Baustein untätig. Den Schlüssel erhältst du beim Kauf über smolabs.de. Ein Schlüssel für den X1 schaltet keinen HomeServer-Baustein frei und umgekehrt.
Changelog
Version 0.1.0
- Erste Version für den HomeServer auf Basis der X1-Bausteine | SMoLabs.
Rezensionen
Es gibt noch keine Rezensionen.