TankerkönigSpritpreise — ReadMe

ÜBERSICHT   —   FREISCHALTUNG  —   SCREENSHOTS

 

  1. Funk­tion­sum­fang
  2. Sys­te­man­forderun­gen
  3. Instal­la­tion
  4. Hin­weise zur Ver­wen­dung
    4.1 Mod­ul-Ein­rich­tung
    4.2 API-Aufrufe
  5. Befehlsref­erenz

 

1. Funktionsumfang

Dieses Mod­ul liest die Sprit­preise über die API von Tankerkönig.de aus.

Ihr müsst euch nur einen API-Key per E‑Mail zuschick­en lassen, dann die entsprechen­den Kon­fig­u­ra­tio­nen in
der Mod­ul-Instanz ein­tra­gen. Es wer­den, unter­halb der Mod­ul-Instanz die Vari­ablen angelegt, in welchen
die entsprechen­den Dat­en der jew­eili­gen Tankstelle(n) abge­spe­ichert werden.

Tankerkönig API Dat­en ste­hen unter der Cre­ative-Com­mons-Lizenz “CC BY 4.0”
https://creativecommons.org/licenses/by/4.0/deed.de

!ACHTUNG! HINWEISE ZUM ABFRAGE-LIMIT DER TANKERKÖNIG-API BEACHTEN!
Siehe 4.2 (Hin­weise zur Ver­wen­dung — API Aufrufe)

Ein­stel­lungsmöglichkeit­en in der Instanz:

  • API Key (Tankerkönig API Key hier anfordern: https://creativecommons.tankerkoenig.de/)
  • Inter­vall (Dat­en der Tankstellen wer­den alle X Sekun­den abge­fragt — min. ist 600 Sekunden)
  • Namen mit ID (wird benötigt, wenn man 2 Tankstellen mit dem gle­ichen Namen im sel­ben Ort hat)
  • Log­ging der Preis-Vari­ablen aktivieren (ja/nein)
  • Sprit­preise in den Vari­ablen mit 2 oder 3 Nachkom­mas­tellen anzeigen
  • Koor­di­nat­en vom Wohnort/Büro/… (Latitude,Longitude — für die Umkreissuche)
  • Radius in km (max. 25km)
  • Sprit­sorte (E5, E10, Diesel, Alle)
  • Sortierung für die Umkreis­suche (Dis­tanz, Preis) — nur inter­es­sant für die Ver­wen­dung der Umkreis­suche per Skript (Array-Sortierung)
  • De/aktivierung von Vari­ablen mit dem niedrigsten/durchschnittlichen/höchsten Preis (ein­stell­bar­er Zeitraum) für die Tankstellen in der Liste der Detail­abfrage (!das Log­ging der Preis-Vari­ablen muss aktiviert sein!)
  • Log­ging der erweit­erten Preis-Vari­ablen (niedrigster/durchschnittlicher/höchster Preis im eingestell­ten Zeitraum) de/aktivieren

Fol­gende Auswahlmöglichkeit­en ste­hen im Mod­ul zur Ver­fü­gung (Mehrfachauswahl möglich):

  • Umkreis­suche (Infos und Preise zu Tankstellen im Radius von 1 bis 25 km)
  • Umkreis­suche — Niedrig­ster Preis (Geöffnete Tankstelle mit dem niedrig­sten Preis für die aus­gewählte Sprit­sorte im aus­gewählten Radius)
  • Detail­abfrage (Detail­in­for­ma­tio­nen zu bes­timmten Tankstellen — Tankstellen ID's in der Instanz eintragen)

Wird eine "Abfragemeth­ode" in der Mod­ul-Instanz abgewählt, dann wer­den die zuge­höri­gen Vari­ablen beim Übernehmen der Ein­stel­lun­gen automa­tisch vom Mod­ul gelöscht!


Umkreis­suche
Hier bekommt ihr alle ver­füg­baren Tankstellen im Umkreis aus­ge­le­sen. Die Dat­en wer­den im eingestell­ten Inter­vall abge­fragt, sowie beim Übernehmen der Ein­stel­lun­gen in der Mod­ul-Instanz.
(Name, Marke, Anschrift, Dis­tanz, Tankstellen-ID, Preis/e, Geöffnet)

Umkreis­suche — niedrig­ster Preis
Hier bekommt ihr die Tankstelle aus­ge­le­sen, die den niedrig­sten Preis und geöffnet hat. Die Dat­en wer­den im eingestell­ten Inter­vall abge­fragt, sowie beim Übernehmen der Ein­stel­lun­gen in der Mod­ul-Instanz.
(Name, Marke, Anschrift, Dis­tanz, Tankstellen-ID, Preis/e, Geöffnet)

Detail­abfrage
Hier bekommt ihr von euren "Stamm-Tankstellen" alle ver­füg­baren Infor­ma­tio­nen aus­ge­le­sen. Die Dat­en wer­den im eingestell­ten Inter­vall abge­fragt, sowie beim Übernehmen der Ein­stel­lun­gen in der Mod­ul-Instanz.
(Name, Marke, Anschrift, Tankstellen-ID, Preis E5, Preis E10, Preis Diesel, Geöffnet, Öff­nungszeit­en [wenn verfügbar], …)

Für die Detail­abfrage müssen erst die ID's der gewün­scht­en Tankstellen per Umkreis­suche ermit­telt und dann in die Mod­ul-Instanz einge­tra­gen wer­den. Danach kann die Umkreis­suche wieder deak­tiviert werden.


Die im Mod­ul gewählten Auswahlen/Einstellungen kön­nen automa­tisch durch einen Timer aktu­al­isiert wer­den. Ihr kön­nt aber auch die Funk­tio­nen mit "_Instanz" ver­wen­den und so die Abfra­gen per Skript durch­führen (die Ergeb­nisse wer­den immer auch als Array zurück­gegeben).
Alter­na­tiv kön­nt ihr eigene Umkreissuchen/Detailabfragen durch­führen, in dem ihr die Funk­tio­nen ohne "_Instanz" ver­wen­det. Weit­ere Infor­ma­tio­nen dazu find­et ihr in dieser Doku­men­ta­tion im Abschnitt "Befehlsref­erenz".

 

2. Systemanforderungen

  • IP-Sym­con ab Ver­sion 4.3

 

3. Installation

Über die Kern-Instanz "Mod­ule Con­trol" fol­gende URL hinzufügen:

https://GITLAB-BENUTZERNAME:GITLAB-PASSWORT@gitlab.com/BY-IPS-Module/TankerkoenigSpritpreise.git
Die Mod­ul-Instanz find­et ihr dort, wo ihr sie angelegt habt.

 

4. Hinweise zur Verwendung

4.1 Modul-Einrichtung

  • Zuerst müssen der API-Key und die Koor­di­nat­en einge­tra­gen werden
  • Danach wird der Radius zur Suche der Tankstellen eingestellt
  • Die Angabe der Sprit­sorte find­et nur bei der Umkreis­suche und bei der Suche des niedrig­sten Preis­es im Umkreis Verwendung
  • Zur Ermit­tlung der Tankstellen-ID's sollte zu Beginn eine Umkreis­suche durchge­führt wer­den
    Hat man über die Umkreis­suche alle für sich inter­es­san­ten Tankstellen und ihre ID's ermit­telt, trägt man diese ID's in die Detail­abfrage ein und deak­tiviert die nor­male Umkreis­suche wieder

4.2 API-Aufrufe

  • Die API-Aufrufe sind bei Tankerkönig.de lim­i­tiert (60 je Stunde), was aber keine wirk­liche Ein­schränkung oder gar ein Prob­lem darstellt!
  • Seit Ver­sion 1.3 von diesem Mod­ul wer­den Detail­abfra­gen von Tankstellen in einem Zwis­chen­spe­ich­er gelagert, so dass eine Detail­abfrage nur ein­ma­lig bei der 1. Abfrage (nach dem IPS-Start und/oder beim Übernehmen von Ein­stel­lun­gen in der Mod­ul-Instanz) "live" durchge­führt wird, danach wer­den die aktuellen Preise und der Öff­nungssta­tus gesam­melt über 1 API-Aufruf ermit­telt und die zuge­höri­gen Detail­in­for­ma­tio­nen (Name, Anschrift, …) wer­den aus dem Zwis­chen­spe­ich­er geholt.
  • Detail­in­for­ma­tio­nen wer­den also nur unter fol­gen­den Umstän­den "live" von Tankerkönig.de abgerufen und erzeu­gen in diesem Moment "viele" API-Aufrufe (1 API-Aufruf je Tankstelle):
    1.) Beim Start von IP-Sym­con
    2.) Beim Übernehmen von geän­derten Ein­stel­lun­gen in der Modul-Instanz
  • Die API-Aufrufe und die Ver­wen­dung des Zwis­chen­spe­ich­ers kön­nen, nach Aktivierung von "Debug" in der Mod­ul-Instanz, im Debug-Fen­ster beobachtet werden
  • Detail­lierte Infor­ma­tio­nen, welche Abfrage wann wie viele API-Aufrufe erzeugt, find­et ihr in der Befehlsref­erenz. Grund­sät­zlich kann man aber sagen, dass jede Abfragemeth­ode (Detail­abfrage, Preis­abfrage, Umkreis­suche, Umkreis­suche niedrig­sten Preis) im nor­malen Betrieb nur noch 1 API-Aufruf erzeugt — ab Mod­ul-Ver­sion 1.3.

 

5. Befehlsreferenz


TKS_Update(int $InstanzID);

> max. 13 API-Aufrufe bei der 1. Abfrage (je nach Auswahl in der Mod­ul-Instanz // max. 2 x Umkreis­suche [bei jed­er Abfrage], 1 x Preis­abfrage, 1 x Detail­in­for­ma­tio­nen für jede Tankstelle [nur bei der 1. Abfrage nach dem IPS-Start])

> bei jed­er fol­gen­den Abfrage wer­den max­i­mal 3 API-Aufrufe benötigt (wenn Detail­in­for­ma­tio­nen, Umkreis­suche und Umkreis­suche niedrig­sten Preis in der Instanz aktiviert sind — was ich NICHT empfehle — siehe "Hin­weise zur Ver­wen­dung")

Ruft die aktuellen Sprit­preise ab und aktu­al­isiert die Variablen.

 

TKS_Detailabfrage(int $InstanzID, string $Tankstel­lenIDs);

> max. 11 API-Aufrufe (1 x Preis­abfrage [bei jed­er Abfrage], 1 x Detail­in­for­ma­tio­nen für jede Tankstelle [nur bei der 1. Abfrage ein­er Tankstelle nach dem IPS-Start])

Gibt ein Array zurück mit Detail­in­for­ma­tio­nen zu allen Tankstellen deren ID's an die Funk­tion übergeben wur­den.
Mehrere Tankstellen-ID's mit Kom­ma getren­nt eingeben! Max­i­mal sind 10 Tankstellen in ein­er Abfrage möglich!

 

TKS_Detailabfrage_Instanz(int $InstanzID);

> max. 11 API-Aufrufe (1 x Preis­abfrage [bei jed­er Abfrage] und 1 x Detail­in­for­ma­tio­nen für jede Tankstelle [nur bei der 1. Abfrage nach dem IPS-Start])

Es wer­den die in der Instanz einge­tra­ge­nen Tankstellen-IDs ver­wen­det. Die Funk­tion aktu­al­isiert die Vari­ablen unter­halb der Mod­ul-Instanz und gibt die Dat­en als Array zurück.

 

TKS_Preisabfrage(int $InstanzID, string $Tankstel­lenIDs);

> 1 API-Aufruf [bei jed­er Abfrage]

Gibt ein Array zurück mit Infor­ma­tio­nen zu den Preisen und dem Öff­nungs-Sta­tus für alle Tankstellen deren ID's an die Funk­tion
übergeben wur­den. Diese Funk­tion liefert, im Gegen­satz zur Funk­tion "TKS_Detailabfrage", nur die Preise zurück und ob die
Tankstelle geöffnet ist.
Mehrere Tankstellen-ID's mit Kom­ma getren­nt eingeben! Max­i­mal sind 10 Tankstellen in ein­er Abfrage möglich!

 

TKS_Umkreissuche(int $InstanzID, string $Lat­i­tude, string $Lon­gi­tude, int $Radius, string $Sortierung, string $Sprit­sporte);

> 1 API-Aufruf (1 x Umkreis­suche [bei jed­er Abfrage])

Gibt ein Array zurück mit den Ergeb­nis­sen der Umkreis­suche.
   — $Radius (1–25km)
   — $Sortierung (price, dist)
   — $Sprit­sorte (E5, E10, Diesel, Alle)

 

TKS_Umkreissuche_Instanz(int $InstanzID);

> max. 2 API-Aufrufe (1 x Umkreis­suche [bei jed­er Abfrage])

Es wer­den die in der Instanz einge­tra­ge­nen Koor­di­nat­en und Ein­stel­lun­gen ver­wen­det. Die Funk­tion aktu­al­isiert die Vari­ablen unter­halb
der Mod­ul-Instanz und gibt die Dat­en als Array zurück.

 

TKS_Umkreissuche_GuenstigsterPreis(int $InstanzID, string $Lat­i­tude, string $Lon­gi­tude, int $Radius, string $Sprit­sorte);

> max. 2 API-Aufrufe (1 x Umkreis­suche [bei jed­er Abfrage], 1 x Detail­in­for­ma­tio­nen zur gün­stig­sten Tankstelle [nur bei der 1. Abfrage ein­er Tankstelle nach dem IPS-Start])

Gibt ein Array zurück mit Detail­in­for­ma­tio­nen zur gün­stig­sten geöffneten Tankstelle in der Nähe.
   — $Radius (1–25km)
   — $Sprit­sorte (E5, E10, Diesel)

 

TKS_Umkreissuche_GuenstigsterPreis_Instanz(int $InstanzID);

> max. 2 API-Aufrufe (1 x Umkreis­suche [bei jed­er Abfrage], 1 x Detail­in­for­ma­tio­nen zur gün­stig­sten Tankstelle [nur bei der 1. Abfrage ein­er Tankstelle nach dem IPS-Start])

Es wer­den die in der Instanz einge­tra­ge­nen Koor­di­nat­en und Ein­stel­lun­gen ver­wen­det. Die Funk­tion aktu­al­isiert die Vari­ablen unter­halb
der Mod­ul-Instanz und gibt die Dat­en als Array zurück.