Back to Home

Tankstellen mit aktuellen Spritpreisen (MTS-K via Informed Sources)

Dieses Dokument beschreibt die REST-Schnittstellen für Tankstellen mit aktuellen Spritpreisen.

Allgemeines

Die aktuellen Spritpreise werden vom Partner "Informed Sources" in Form von zwei Dateien heruntergeladen. Die erste Datei enthält die Tankstellendaten, die zweite Datei die aktuellen Spritpreise sowie spezifische Zeiträume, wo die Tankstelle geänderte Öffnungszeiten hat (z.B. am 24.12.) , oder wo die Tankstelle geschlossen ist (z.B. Urlaub, Feiertage). Die erste Datei wird vom Partner wöchentlich aktualisiert. Die zweite Datei wird vom Partner kontinuierlich aktualisiert, und soll alle 5 Minuten abgeholt werden. Die Daten umfassen nur Tankstellen in Deutschland. Zum Zeitpunkt der Implementierung gab es Daten für 14.763 Tankstellen.

Damit die aktuellen Spritpreise schnell in die ContentAPI übernommen werden können, erhalten sie einen eigenen Index, der auf schnelle Importe und Abfragen ausgelegt ist. Als Primärschlüssel für die Tankstellen in diesem Index werden die vom Partner "Informed Sources" vergebenen GUIDs verwendet, z.B. "b0bf848e-f960-4947-afd0-dba4fc16ec5d".

Die Tankstellen werden zusätzlich noch wöchentlich ohne Spritpreise als normale POIs importiert.

Schnittstellen

Abfragen einer Tankstelle

User Story Ein User kann eine Tankstelle anhand der Tankstellen-GUID abfragen.
HTTP GET
URL http://api.mairdumont.com/data/poi/api/petrol/

Es kommen Informationen zu einer Tankstelle zurück.

Abfrage der Tankstellen über eine Umkreissuche

User Story Ein User kann Tankstellen über eine Umkreissuche abfragen.
HTTP GET
URL http://api.mairdumont.com/data/poi/api/petrol/all?circle=,,

Die Distanz wird in Metern angegeben. Es kommen Informationen zu den Tankstellen zurück.

Abfrage der Tankstellen über eine BoundingBox-Suche

User Story Ein User kann Tankstellen über eine Boundingbox abfragen.
HTTP GET
URL http://api.mairdumont.com/data/poi/api/petrol/all?bbox=,,,

Es kommen Informationen zu den Tankstellen zurück.

Abfragen der Tankstellen über eine Korridorsuche

User Story Ein User kann Tankstellen entlang eines Korridors abfragen.
HTTP POST
URL http://api.mairdumont.com/data/poi/api/petrol/corridor

Als Content-Type für den Request-Body kann "application/json" oder "application/xml" verwendet werden. Es kommen Informationen zu den Tankstellen zurück.

Beispiel für Request-Body mit Korridor, BoundingBox und Distanz bei Content-Type "application/json":

Korridorsuche

{
        "geometry": {
            "type": "LineString",
            "coordinates": [[9.18299,48.77582],[9.1854,48.78191],[9.17963,48.78457],[9.18295,48.79968],[9.18364,48.80988],[9.17374,48.82248],[9.17147,48.82479],[9.16752,48.83615],[9.17033,48.84049],[9.14623,48.84016],[9.12333,48.8499],[9.15458,48.90357],[9.15554,48.91718],[9.16448,48.92568],[9.19267,48.93892],[9.22334,48.96532],[9.23291,48.99338],[9.24683,49.01533],[9.2556,49.03633],[9.26903,49.05793],[9.28889,49.08087],[9.30282,49.11547],[9.30149,49.13036],[9.30601,49.14249],[9.30045,49.15511],[9.31348,49.15661],[9.33275,49.16243],[9.36841,49.16212],[9.38703,49.17373],[9.41457,49.18197],[9.41987,49.19107],[9.43259,49.19505],[9.47294,49.20414],[9.50364,49.21134],[9.53763,49.21172],[9.58144,49.2161],[9.66938,49.20435],[9.75653,49.18134],[9.82787,49.17307],[9.93662,49.17715],[10.01673,49.17337],[10.04434,49.18289],[10.08635,49.18423],[10.15936,49.21049],[10.22358,49.20368],[10.24031,49.20416],[10.25328,49.21288],[10.28435,49.22746],[10.35159,49.24159],[10.40596,49.25177],[10.44194,49.25365],[10.47312,49.24974],[10.49543,49.25724],[10.53016,49.2638],[10.63175,49.24985],[10.6914,49.26466],[10.73221,49.28936],[10.77108,49.30553],[10.82097,49.30784],[10.87883,49.31574],[10.93249,49.30275],[11.02862,49.31321],[11.09236,49.34711],[11.14926,49.38564],[11.20228,49.39534],[11.19585,49.40949],[11.23263,49.44636],[11.28555,49.49969],[11.31345,49.5248],[11.32594,49.56069],[11.35902,49.59159],[11.36482,49.60191],[11.38683,49.6142],[11.4227,49.63261],[11.43767,49.64827],[11.46237,49.65948],[11.46911,49.66844],[11.46684,49.68582],[11.46522,49.69861],[11.47257,49.71133],[11.48852,49.72241],[11.50951,49.72822],[11.51557,49.7377],[11.50956,49.7563],[11.50607,49.76862],[11.51283,49.78139],[11.49692,49.79236],[11.49398,49.80076],[11.50058,49.81011],[11.49969,49.82871],[11.51626,49.85217],[11.52226,49.87033],[11.57263,49.88202],[11.59678,49.88686],[11.60484,49.9168],[11.60781,49.95336],[11.60776,49.98912],[11.61028,50.00418],[11.60604,50.01426],[11.60798,50.03442],[11.61821,50.05672],[11.62428,50.06808],[11.63686,50.0736],[11.6666,50.08189],[11.69958,50.09963],[11.7335,50.12298],[11.74579,50.14687],[11.746,50.16924],[11.776,50.20331],[11.78202,50.22304],[11.77811,50.23784],[11.8113,50.28132],[11.809,50.29688],[11.79892,50.31597],[11.78796,50.33523],[11.78135,50.3564],[11.79071,50.369],[11.79127,50.37685],[11.77784,50.38684],[11.76371,50.39758],[11.77422,50.40568],[11.78731,50.41874],[11.80302,50.43856],[11.80212,50.46279],[11.80345,50.48276],[11.80213,50.49415],[11.79259,50.50384],[11.79934,50.5242],[11.80479,50.53222],[11.80245,50.5429],[11.79307,50.55037],[11.77579,50.57037],[11.7923,50.61615],[11.80138,50.64535],[11.81212,50.6556],[11.82281,50.67116],[11.85293,50.71191],[11.84769,50.72617],[11.85056,50.73544],[11.87632,50.76114],[11.88914,50.78134],[11.89537,50.79073],[11.89555,50.8038],[11.89186,50.81474],[11.88329,50.8226],[11.86588,50.84115],[11.85046,50.86859],[11.84007,50.92213],[11.83421,50.9473],[11.84458,50.95779],[11.86232,50.97078],[11.889,50.98256],[11.9094,50.98925],[11.92232,51.00574],[11.94289,51.04901],[11.95235,51.06381],[11.95574,51.08482],[11.95995,51.12622],[11.97911,51.14818],[12.04185,51.21936],[12.08445,51.25759],[12.14531,51.29761],[12.17811,51.33359],[12.18947,51.3613],[12.18192,51.38833],[12.18714,51.40829],[12.21407,51.45507],[12.21461,51.47695],[12.20262,51.49706],[12.19744,51.51733],[12.18876,51.55379],[12.1906,51.58023],[12.1843,51.60475],[12.20211,51.65348],[12.21382,51.71524],[12.23077,51.75577],[12.24055,51.76638],[12.27589,51.79309],[12.31483,51.82787],[12.32708,51.8449],[12.34572,51.85689],[12.37322,51.8681],[12.39452,51.88207],[12.40366,51.89269],[12.43002,51.91163],[12.44262,51.92155],[12.45768,51.95543],[12.48302,51.96966],[12.53314,51.98558],[12.5899,52.02027],[12.61587,52.03327],[12.64498,52.05086],[12.68347,52.09176],[12.7394,52.12219],[12.7846,52.16065],[12.83835,52.17851],[12.88165,52.19919],[12.91311,52.22802],[12.91721,52.24077],[12.90888,52.25587],[12.91387,52.28258],[12.91843,52.29023],[12.95671,52.29922],[13.01077,52.30333],[13.04211,52.29987],[13.07936,52.29952],[13.10682,52.328],[13.14076,52.34326],[13.14069,52.35949],[13.14622,52.36581],[13.15015,52.37962],[13.16258,52.39127],[13.19369,52.40783],[13.19676,52.41757],[13.19464,52.42409],[13.19146,52.42887],[13.2001,52.44021],[13.23824,52.47038],[13.28074,52.50155],[13.28623,52.51158],[13.31515,52.51208],[13.35087,52.51413],[13.40495,52.52001]]
        },
        "distance": 2000,
        "boundingBox": {
            "northwest": {
                "lat": 52.6,
                "lon": 9.1
            },
            "southeast": {
                "lat": 48.7,
                "lon": 13.5
            }
        }
    }

Parameterübersicht

Parameter Wert Beschreibung
circle ,, Sucht nach Tankstellen im Umkreis um einen spezifizierten Suchmittelpunkt. Der Suchmittelpunkt wird über Breiten- und Längengrad im WGS84 Format angegeben. Zudem wird der Suchradius in Metern angegeben, z.B. "circle=52.52223,13.41637,25000". Die Werte werden durch Kommas getrennt.
bbox ,,, Sucht nach Tankstellen innerhalb der spezifizierten BoundingBox. Die Koordinaten müssen in der Reihenfolge Norden, Westen, Süden, Osten angegeben werden, Koordinaten in WGS-84, Bsp.: "bbox=48.999,13.2,48.9,13.5".
petrol "diesel" (default), "e5" oder "e10" (default) Der gewünschte Sprittyp wird bei der Sortierung nach Preis relevant. Die Tankstellen werden nach den Preis für den gewünschten Sprittyp aufsteigend sortiert. Tankstellen, bei denen der gewünschte Sprittyp nicht angeboten werden, was normalerweise auf Eingabefehler bei MTS-K zurückzuführen ist, werden bei der Sortierung nach Spritpreisen ans Ende sortiert.
datetime Datumsformat "yyyy-MM-dd'T'HH:mm:ss" Über den "datetime" Parameter können Datum und Uhrzeit für die Prüfung der Öffnungszeiten festgelegt werden, z.B. "2017-12-24T16:30:00". Wird der Parameter nicht angegeben, so wird das aktuelle Datum und Uhrzeit verwendet.
pbrand Tankstellenkette, z.B. "OMV,JET" Sucht nach Tankstellen mit passendem Tankstellenkette ("brand"). Verschiedene Tankstellenketten können durch Kommas getrennt angegeben werden. Aktuell werden folgende Tankstellenketten unterstützt:

ARAL, AVIA, Agip, BFT, BayWa, CLASSIC, Calpam, ED, ELAN, ESSO, GO, HEM, Hoyer, JET, Markant, OIL!, OMV, Q1, Raiffeisen, SCORE, STAR, Shell, Sonstige, Sprint, TAMOIL, TOTAL, Team, Westfalen
title Tankstellenname, z.B. "ARAL" Sucht nach Tankstellen mit passendem Namen.
loc Ortsname, z.B. "Stuttgart" Sucht nach Tankstellen im passendem Ortsnamen.
sort "price" (default), "dist", "brel" Gibt die Sortierreihenfolge der Tankstellen vor. Als primäre Sortierung wird immer geprüft, ob die Tankstelle aktuell (oder zu dem gewünschten Zeitpunkt) offen ist. Geschlossene Tankstellen werden ans Ende sortiert. Erst dann kommt die sekundäre Sortierung zum Einsatz, welche über den Parameter "sort" gewählt wird. Bei "price" werden die Tankstellen nach dem Preis für den gewünschten Sprittyp aufsteigend sortiert. Bei gleichem Preis wird bei Umkreissuche und BoundingBox-Suche nach Distanz zum Suchmittelpunkt sortiert. Bei "dist" werden die Tankstellen nach Distanz zum Suchmittelpunkt (Umkreissuche und BoundingBox-Suche) sortiert, dabei wird auf den Tankstellen auch die Luftlinien-Distanz zum Suchmittelpunkt in Metern ausgegeben. Die Sortierung "brel" gruppiert die Tankstellen nach Marke.
startindex Ganzzahl >= 0 Der Parameter "startindex" bestimmt, ab welcher Tankstelle die Ausgabe begonnen werden soll. Dies wird als Blättern bezeichnet. Der Vorgabewert ist 0, d.h. die Ausgabe wird mit der ersten Tankstelle begonnen. Zum Blättern sollte der startindex jeweils um den Wert von itemsperpage erhöht werden. Gibt es insgesamt 70 Tankstellen, so werden diese bei "itemsperpage=10" auf 7 Seiten (mit jeweils 10 Tankstellen pro Seite) ausgegeben. Beim Blättern erhält "startindex" nacheinander die Werte 0, 10, 20, 30, 40, 50 und 60. Bei "itemsperpage=15" wären die Werte für "startindex" demnach 0, 15, 30, 45 und 60.
itemsperpage Ganzzahl zwischen 1 und 1000, default 10. Die Anzahl der Tankstellen pro Seite, siehe auch Parameter "startindex".

Ergebnisformat

Die Tankstellen werden wie gewohnt mit einem Wrapper-Objekt umschlossen, welche neben den eigentlichen Treffern "entries" auch die Elemente "totalResults" (Gesamtzahl der Treffer für Suchanfrage), "startIndex" (Wert für Parameter "startindex"), "itemsPerPage" (Wert für Paramter "itemsperpage") und "searchTime" (Verarbeitungsdauer in ContentAPI) enthält.

Beispiel für Tankstellensuche

{
      "entries": [
        {
          "id": "92f703e8-0b3c-46da-9948-25cb1a6a1514",
          "title": "Stuttgart, Hackstraße 6",
          "brand": "Sonstige",
          "priceDiesel": 1.089,
          "priceE10": 1.249,
          "priceE5": 1.289,
          "coordinates": {
            "lat": 48.7891,
            "lon": 9.197897
          },
          "address": {
            "country": "Deutschland",
            "isoCountryCode": "DE",
            "zip": "70190",
            "location": "Stuttgart",
            "street": "Hackstraße 6"
          },
          "openingHours": {
            "openNow": true,
            "periods": [ ... ],
            "weekdayText": [
              "<span class=\"cntapi_petrol_weekday\">Montag:</span><span class=\"cntapi_petrol_time\">06:00 - 22:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Dienstag:</span><span class=\"cntapi_petrol_time\">06:00 - 22:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Mittwoch:</span><span class=\"cntapi_petrol_time\">06:00 - 22:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Donnerstag:</span><span class=\"cntapi_petrol_time\">06:00 - 22:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Freitag:</span><span class=\"cntapi_petrol_time\">06:00 - 22:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Samstag:</span><span class=\"cntapi_petrol_time\">06:00 - 22:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Sonntag:</span><span class=\"cntapi_petrol_time\">08:00 - 22:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Feiertag:</span><span class=\"cntapi_petrol_time\">08:00 - 22:00 Uhr</span>"
            ],
            "nextOpenNowChange": 1506974400000,
            "nextOpenNowChangeFormatted": "2017-10-02 22:00:00 +0200"
          },
          "stationLastUpdate": 1502947800000,
          "stationLastUpdateFormatted": "2017-08-17 07:30:00 +0200",
          "pricesLastUpdate": 1503067440000,
          "pricesLastUpdateFormatted": "2017-08-18 16:44:00 +0200"
        },
        {
          "id": "855e5469-1572-4e20-a984-c351cca5d2b5",
          "title": "AVIA Xpress Automatenstation Stuttgart-Wangen",
          "brand": "AVIA",
          "priceDiesel": 1.079,
          "priceE10": 1.259,
          "priceE5": 1.279,
          "coordinates": {
            "lat": 48.7815,
            "lon": 9.22926
          },
          "address": {
            "country": "Deutschland",
            "isoCountryCode": "DE",
            "zip": "70188",
            "location": "Stuttgart",
            "street": "Neckarwiesenstr.",
            "number": "7"
          },
          "openingHours": {
            "openNow": true,
            "open24h": true,
            "periods": [ ... ],
            "weekdayText": [
              "<span class=\"cntapi_petrol_weekday\">Montag:</span><span class=\"cntapi_petrol_time\">24 Stunden ge&ouml;ffnet</span>",
              "<span class=\"cntapi_petrol_weekday\">Dienstag:</span><span class=\"cntapi_petrol_time\">24 Stunden ge&ouml;ffnet</span>",
              "<span class=\"cntapi_petrol_weekday\">Mittwoch:</span><span class=\"cntapi_petrol_time\">24 Stunden ge&ouml;ffnet</span>",
              "<span class=\"cntapi_petrol_weekday\">Donnerstag:</span><span class=\"cntapi_petrol_time\">24 Stunden ge&ouml;ffnet</span>",
              "<span class=\"cntapi_petrol_weekday\">Freitag:</span><span class=\"cntapi_petrol_time\">24 Stunden ge&ouml;ffnet</span>",
              "<span class=\"cntapi_petrol_weekday\">Samstag:</span><span class=\"cntapi_petrol_time\">24 Stunden ge&ouml;ffnet</span>",
              "<span class=\"cntapi_petrol_weekday\">Sonntag:</span><span class=\"cntapi_petrol_time\">24 Stunden ge&ouml;ffnet</span>"
            ]
          },
          "stationLastUpdate": 1502947800000,
          "stationLastUpdateFormatted": "2017-08-17 07:30:00 +0200",
          "pricesLastUpdate": 1503067440000,
          "pricesLastUpdateFormatted": "2017-08-18 16:44:00 +0200"
        },
        {
          "id": "182575fd-26f6-4ab1-89f4-618ed5b75683",
          "title": "Stuttgart",
          "brand": "Sonstige",
          "priceDiesel": 1.079,
          "priceE10": 1.269,
          "priceE5": 1.289,
          "coordinates": {
            "lat": 48.81492,
            "lon": 9.177997
          },
          "address": {
            "country": "Deutschland",
            "isoCountryCode": "DE",
            "zip": "70469",
            "location": "Stuttgart",
            "street": "Heilbronner Straße",
            "number": "309"
          },
          "openingHours": {
            "openNow": true,
            "periods": [ ... ],
            "overrideOpen": [ ... ],
            "overrideClose": [ ... ],
            "weekdayText": [
              "<span class=\"cntapi_petrol_weekday\">Montag:</span><span class=\"cntapi_petrol_time\">08:00 - 19:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Dienstag:</span><span class=\"cntapi_petrol_time\">08:00 - 19:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Mittwoch:</span><span class=\"cntapi_petrol_time\">08:00 - 19:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Donnerstag:</span><span class=\"cntapi_petrol_time\">08:00 - 19:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Freitag:</span><span class=\"cntapi_petrol_time\">08:00 - 19:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Samstag:</span><span class=\"cntapi_petrol_time\">08:00 - 19:00 Uhr</span>",
              "<span class=\"cntapi_petrol_weekday\">Sonntag:</span><span class=\"cntapi_petrol_time\">Geschlossen</span>"
            ],
            "overrideText": [
              "<span class=\"cntapi_petrol_override_close\">Am 03.10.2017 geschlossen.</span>",
              "<span class=\"cntapi_petrol_override_close\">Am 31.10.2017 geschlossen.</span>",
              "<span class=\"cntapi_petrol_override_close\">Am 01.11.2017 geschlossen.</span>"
            ],
            "nextOpenNowChange": 1506963600000,
            "nextOpenNowChangeFormatted": "2017-10-02 19:00:00 +0200"
          },
          "stationLastUpdate": 1502947800000,
          "stationLastUpdateFormatted": "2017-08-17 07:30:00 +0200",
          "pricesLastUpdate": 1503067440000,
          "pricesLastUpdateFormatted": "2017-08-18 16:44:00 +0200"
        },
        ...
      ],
      "totalResults": 71,
      "startIndex": 0,
      "itemsPerPage": 10,
      "title": "Anzeigen der Tankstellendaten",
      "searchTime": 90
    }

Das Flag "openNow" bei "openingHours" ist "true", wenn die Tankstelle aktuell (bzw. zum angefragten Zeitpunkt) geöffnet ist.

Das Flag "open24h" bei "openingHours" ist "true", wenn die Tankstellen an allen Tagen in der Woche 24 Stunden geöffnet hat (24/7).

Unter "weedkayText" bei "openingHours" werden die Öffnungszeiten als Text für die Ausgabe mitgegeben. Dabei ist der aktuelle Tag (bzw. der angefragte Tag) immer oben. Zusätzliche Angaben, bei besonderen Öffnungs- oder Geschlossen-Zeiten, werden am Ende ausgegeben.