GTI Anwenderhandbuch
öffentlicher Teil
Version 61.1
für API-Version 61
HBT Hamburger Berater Team
Stadthausbrücke 3, 20355 Hamburg
Tel: +49 40 369779-0
Fax: +49 40 369779-99
info@hbt.de, www.hbt.de
Das GEOFOX Thin Interface, im folgenden GTI genannt, ist eine REST-ähnliche Web-Service-Schnittstelle für GEOFOX. Die Kommunikation erfolgt per HTTP, im Body werden Requests und Responses in den Formaten JSON oder XML transportiert. Sie löst die bisherige SOAP-Schnittstelle ab und befindet sich in laufender Entwicklung.
Eine Motivation zur Entwicklung des GTI als SOAP-Nachfolger war die zusätzliche Eignung für mobile Geräte, dabei sollte die Eignung zur Server-Server-Kommunikation natürlich beibehalten werden.
Für die mobile Nutzung war neben Overheadreduktion und guter Parsbarkeit die Erweiterung der Authentifizierung um dynamische IPs wichtig.
Alle Methoden werden per HTTP-POST aufgerufen und mit dem UTF-8-codierten Request im HTTP-Body gesendet. In Tabelle 1 werden die Felder eines Geofox-HTTP-Paketes genannt. Über den Header X-Platform kann die Plattform des Klienten angegeben werden. Wenn möglich sollte X-Platform einen Wert aus Tabelle 2 enthalten.
| Header-Name | Typ | Default-Wert/Beschreibung |
| Content-Type | application/json oder | text/plain, wird |
| application/xml | nicht unterstützt, daher | |
| ist dieses Feld obligatorisch | ||
| Accept-Encoding | gzip, deflate | Unkomprimiert |
| Accept | application/json oder | Gewünschter Content-Type |
| application/xml | der Antwort | |
| Benutzerdefinierte Header-Felder :
| ||
| geofox-auth-signature | Signatur, siehe Kapitel 1.3 Authentifikation | |
| geofox-auth-user | Application-ID (wird | |
| von der HBT GmbH vergeben) | ||
| geofox-auth-type | Algorithmus zur | HmacSHA1 |
| Signaturerstellung | ||
| X-Platform | (Optional) Betriebssystem des Klienten, | ungesetzt |
| z.B. ios, android, winphone, web, mobile | ||
Ein Beispiel für einen GTI-HTTP-POST-Request zeigt Listing 1.
1POST /gti/public/init HTTP/1.1 2Accept: application/json 3Content-Type: application/json;charset=UTF-8 4geofox-auth-type: HmacSHA1 5geofox-auth-user: gnw 6geofox-auth-signature: G9sE5wm9vpYu441iJ7Ag5vPKerw= 7User-Agent: JUnitTest 8X-TraceId: f144f2e3-c5f6-42fd-bf3d-27be4ede899b 9Content-Length: 2 10Host: gti.geofox.de 11Connection: Keep-Alive 12 13{}
Als TraceID wird das optionale Feld X-TraceId im HTTP-Header bezeichnet, es identifiziert einen Request. Zu verwenden ist eine UUID gemäß RFC4122. Weil alle Backendsysteme diesen Parameter erhalten und loggen, wird ein Debuggen einzelner Request erleichtert – es empfiehlt sich folglich eine Verwendung und Ausgabe derselben in sämtlichen Fehlerprotokollen.
Die Kommunikation (Requests und Responses) im HTTP-Body kann in den Formaten JSON oder XML codiert sein.
In Listing 2 wird ein Beispiel von einem CNRequest im JSON-Format gegeben.
1{ 2 "coordinateType": "EPSG_4326", 3 "maxList": 1, 4 "theName": { 5 "name": "Altona", 6 "type": "STATION" 7 } 8}
In Listing 3 wird ein Beispiel für eine CNResponse im JSON-Format gegeben.
1{ 2 "results": [ 3 { 4 "name": "Altona", 5 "id": "Master:80953", 6 "type": "STATION", 7 "city": "Hamburg", 8 "coordinate": { 9 "x": 9.93454, 10 "y": 53.552405 11 } 12 } 13 ], 14 "returnCode": "OK" 15}
Listing 4 zeigt ein Beispiel für ein CNRequest im XML-Format.
1<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 2<gti:CNRequest xmlns:gti="http://www.geofox.de/schema/geofoxThinInterface"> 3 <theName> 4 <name>Altona</name> 5 <type>STATION</type> 6 </theName> 7 <maxList>1</maxList> 8 <coordinateType>EPSG_4326</coordinateType> 9</gti:CNRequest>
Listing 5 zeigt ein Beispiel für ein CNResponse im XML-Format.
1<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 2<gti:CNResponse xmlns:gti="http://www.geofox.de/schema/geofoxThinInterface"> 3 <returnCode>OK</returnCode> 4 <results> 5 <name>Altona$<$/name> 6 <city>Hamburg</city> 7 <id>Master:80953</id> 8 <type>STATION</type> 9 <coordinate> 10 <x>9.93454</x> 11 <y>53.552405</y> 12 </coordinate> 13 </results> 14</gti:CNResponse>
Wenn die Zugriffe von einem oder mehreren Servern mit statischer IP-Adresse geschieht, können diese Adressen zur Authentifizierung des Benutzers verwendet werden. Um innerhalb einer authorisierten IP-Adresse zwischen unterschiedlichen Benutzern unterscheiden zu können, kann zusätzlich über das HTTP-Header-Feld geofox-auth-user ein Benutzername mit angegeben werden.
Alternativ gibt es insbesondere für dynamische IP-Adressen die Möglichkeit, sich mittels Benutzernamen und Signatur über die HTTP-Header Felder geofox-auth-user und geofox-auth-signature zu authentifizieren. Die zu verwendende Signatur ist ein hash-basierender Code (hash-based message authentication code gemäß RFC2104, kurz HMAC) aus Request-Body und UTF-8 kodiertem Passwort. Der Hashcode wird dabei mit dem Verfahren SHA1 gebildet und Base64-codiert gesendet. Beispielcode zur Erstellung einer Signatur in Objective-C (iOS) und Java (z.B. für Android) ist in Abschnitt 3 zu finden.
Die Einrichtung von Benutzerkonten erfolgt durch die HBT GmbH.
Der Entwickler von Client-Applikation hat dafür zu sorgen, dass das Passwort im Client für Dritte nicht leicht auffindbar und sicher gespeichert ist. Dazu gehört der Einsatz von Verschlüsselung und/oder Code-Obfuscation.
Alle Methoden nehmen nur ein Objekt als Request und geben nur ein Objekt als Response zurück, es gibt für jede Methode ein eigenes Request- und Response-Objekt.
Alle Requests erben (i.d.R. direkt) von BaseRequestType und erben damit dessen Felder language, version und filterType, die hier besprochen werden. Alle Responses erben (stets direkt) von BaseResponseType Felder zur Fehlerbehandlung, die in Kapitel 5 gesondert behandelt wird.
Über dieses Feld ist eine Abwärtskompatibilität implementiert. In jedem Request ist im Feld version in BaseRequestType die Versionsnummer der API zu übermitteln, die dem Client bekannt ist, so dass der Server die Response auf diese API-Version zuschneiden kann.
Der Default-Wert für das version-Feld ist 1 – Da diese Version jedoch mitlerweile veraltet ist, sollte in jedem Request die gewünschte Version mit übertragen werden. Eine kleine API-Versionshistorie kann aus der Versionshistorie dieser Dokumentation in Anhang C abgeleitet werden.
Die default-Sprache des Systems für übersetzbare Textfelder, wie Anmerkungen und Namen von Bereichen und Fahrkarten, ist deutsch. Sie kann mit dem optionalen Feld language explizit auf en (für englisch) oder de (für deutsch) gesetzt werden.
Dies betrifft die Ausgabe von Anmerkungen, Ticketnamen, HVV-Zonen und ähnlichem, nicht jedoch die Namen von Haltestellen.
Der Geofox-Datenbestand ist sehr groß und umfasst viele Haltestellen, Linien und Tarifgebiete. Enthalten sind neben dem öffentlichen Personennahverkehr des HVV auch Fernverkehrsverbindungen der Deutschen Bahn und diversen Bus- und Bahnlinien in Schleswig-Holstein und anderen Bereichen.
Eine Besonderheit sind die ausbrechenden Linien; das sind die, die prinzipiell im HVV liegen, die aber ein paar letzte Stationen samt Endhaltestelle außerhalb des HVV-Bereiches haben. Das Teilstück der Linie im HVV-Bereich zählt dann als Linie im HVV. Beispiele dafür sind alle Regionalbahnen oder Buslinien wie die 410 und die 412.
Das GTI bietet die Möglichkeit, über einen Filter die betrachtete Region einzustellen. Derzeit gibt es die beiden Möglichkeiten, entweder ausschließlich den HVV-Bereich (inklusive HVV-Teilstücken von ausbrechenden Linien) oder den gesamten, ungefilterten Geofox-Datenbestand zu betrachten.
Dies wird in allen Requests über das von BaseRequestType geerbte Enum filterType festgelegt, es ist vom Typ FilterType. Derzeit gibt es die Werte HVV_LISTED und NO_FILTER. Die öffentliche Schnittstelle ist dabei auf HVV-Linien beschränkt, es wird daher immer auf den Wert HVV_LISTED gesetzt und die Reichweite damit auf das Gebiet des HVVs beschränkt.
Im Client sind Parser so zu implementieren, dass eine Erweiterung (auch innerhalb einer API-Version) nicht zu Fehlfunktionen führt. Empfehlungen für Parser werden in Kapitel 3 gegeben.
Es wird eine kleine Einführung in die Begriffe des GTI-Routings gegeben. Oft ist die Abgrenzung nicht ganz scharf, die Bedeutung ergibt sich jedoch stets aus dem Kontext.
Einige Felder bezeichnen Tage, sie werden üblicherweise mit date bezeichnet, Uhrzeiten im Feld time. Es werden dabei Strings gespeichert, die sehr flexibel sind: Beispiele sind 27.03.2014, montags und heute für date sowie 18:05, 14-16, jetzt für time. Der Typ GTITime kombiniert diese, er enthält genau ein Feld date und ein Feld time.
Der Typ dateTime enthält Datum und Zeitpunkt in einem Feld. Es ist im Pattern
yyyy-MM-dd’T’HH:mm:ss.SSSZ zu codieren.
Ein Beispiel dafür ist 2015-09-21T08:24:06.634+0200.
Koordinaten geben einen Punkt auf der Erdoberfläche in zwei double-Werten an, sie werden z.B. in JSON mit "coordinate:{*:9.962371, "y:53.569501} notiert.
Das GTI arbeitet per default mit Koordinaten im Format EPSG-4326 (WGS84). Unterstützt wird außerdem EPSG-31467 (System nach Gauß/Krüger, angewendet in Zone 3). Das Enum CoordinateType steuert dies, die zugehörigen Werte sind EPSG_4326 und EPSG_31467. Zusätzlich kann der Client den gewünschten Koordinatentyp in der Antwort vorgeben.
Die verschiedenen Linien von z.B. Bussen und U-Bahnen werden über ID-Strings identifiziert. Diese folgen dem Schema L:N_B oder L:N_B_X, dabei steht das N für den Namen der Linie, das B steht für den Betreiber, das X ist ein optionaler Zusatz. Eine Linie hat keine Richtung, also auch keine Anfangs- und Endhaltestelle. Beispiele für Line Keys sind VHH:569_VHH für die Buslinie 569, ZVU-DB:S1_ZVU-DB_S-ZVU bezeichnet die S-Bahn S1.
In der Schnittstelle gibt es einige Felder, die als Zeit in Minuten nach einem bestimmten Zeitpunkt angegeben sind. Diese sind immer als reale Minuten zu interpretieren. Beispiel: Wenn eine departureList um 01:30 Uhr am Tag der Zeitumstellung im Frühjahr abgefragt wird, und die Antwort enthält eine Abfahrt (Departure) mit der Zeit (time) 120 min., dann ist hier nicht etwa 03:30 Uhr gemeint, sondern 04:30 Uhr, da die Zeit von 2 Uhr auf 3 Uhr an diesem Tag vor gestellt wurde und somit zwischen 01:30 Uhr und 04:30 Uhr nur 120 min. vergangen sind.
Auf https://gti.geofox.de/gti/public?_wadl&_type=xml ist eine Beschreibung des GTI im Format WADL (Web App Description Language1) abrufbar. Die WADL-Datei gibt Auskunft über die verfügbaren Methoden, deren URL, zulässige MIME-Typen sowie Struktur von Request und Response. Im Zweifel gilt diese WADL als Referenz.
Es ist möglich, den aktuell für die Fahrplanauskunft verwendeten Soll-Fahrplan unter der URL https://gti.geofox.de/gti/data/Plandaten.zip abzurufen. Voraussetzung dafür ist die Authentifizierung mittels des GTI-Accounts per Basic Auth. Der Fahrplan liegt im ISA-Format (IVU.pool-Standard-ASCII-Schnittstelle) der Firma IVU Traffic Technologies AG vor. Für weitere Informationen zum Soll-Fahrplan und dem Datenformat bitte an api@hochbahn.de wenden.
Einige der bereitgestellten Methoden (z.B. getRoute, departureList, departureCourse) stellen zusätzlich zu den Plandaten auch Echtzeitinformationen zur Verfügung. Diese Verspätungen, Ausfälle, Verstärkerfahrten und Gleisänderungen werden in GTI generell in den Feldern delay (bzw. depDelay und arrDelay), cancelled, extra und realtimePlatform angegeben. Zur Nutzung von Echtzeitinformationen müssen hierbei in den jeweiligen Methoden (getRoute, departureList, getVehicleMap) die diesbezüglichen Flags (realtime bzw. useRealtime), wie in der Spezifikation beschrieben, gesetzt werden.
Wir behalten uns vor, inaktive Benutzer nach einem Jahr zu löschen.
Benutzern, welche im Schnitt mehr als einen API-Aufruf pro Sekunde tätigen, wird der API-Zugang temporär gesperrt.
Die Tabelle 3 gibt eine Übersicht über die aktuellen Methoden des APIs.
|
Methode, URL |
Beschreibung |
|
Init |
Abrufen allgemeiner Systeminformationen |
|
checkName
|
Finden von für das System verwertbaren Orten |
|
getRoute
|
Finden einer optimalen Route |
|
departureList
|
Finden der Abfahrten einer Haltestelle |
|
getTariff
|
Finden von Tarif-Informationen zu einer Route |
|
departureCourse
|
Anfragen des Verlaufes (Haltestellenabfolge) einer Fahrt |
|
listStations
|
Ermöglicht Erstellung und Pflege eines Haltestellen-Caches im Client |
|
listlines
|
Anfragen aller Linien, die seit einer Datenversion eine Änderung erfahren haben |
|
getAnnouncements
|
Anfragen von aktuellen Bekanntmachungen wie Fahrplanabweichungen |
|
checkPostalCode
|
Überprüfung, ob eine Postleitzahl im HVV Gebiet liegt |
|
getVehicleMap
|
Gibt alle Fahrzeuge und deren Bewegung in einer bestimmten Gegend zu einer bestimmten Zeit zurück |
|
getTrackCoordinates
|
Gibt die Koordinaten zu bestimmten Streckenabschnitten zurück |
|
getIndividualRoute
|
Komplementäre Mobilität: Finden einer optimalen individuellen Route |
|
getStationInformation
|
Abruf zusätzlicher Informationen einer Haltestelle |
|
tariffMetaData
|
Liefert diverse statische Tarif-Informationen |
|
singleTicketOptimizer
|
Tarifberater für Gruppen |
|
ticketList
|
Liefert eine Liste der Fahrkarten im HVV mit diversen Eigenschaften |
Die folgenden Klassendiagramme geben eine Übersicht zum Aufbau von Requests und Responses. Einige Details sind dabei zur besseren Übersicht nicht genannt. Die Grafiken sind lediglich als Verständniserleichterung gedacht, im Zweifel ist die WADL als Referenz anzusehen.
Im Folgenden werden die verfügbaren Methoden vorgestellt.
Jede Methode hat nur ein Objekt als Parameter und gibt nur ein Objekt zurück, welches genau auf die Methode zugeschnitten ist. Die Methode checkName (kurz „CN”) nimmt ein CNRequest und gibt ein CNResponse zurück. Dieses Namensschema gilt dabei für andere Methoden analog. Die Requests erben Felder von BaseRequestType, Responses erben Felder (zur Fehlerbehandlung) von BaseResponseType. Diese und ihre Felder sind in Abschnitt 1.4 vorgestellt und werden bei der folgenden Besprechung der einzelnen GTI-Methoden nicht wiederholt, obwohl sie natürlich vorhanden sind und ggf. auch ausgewertet werden.
Tritt kein Fehler auf, enthält jede Response das Key/Value-Paar "returnCode":"OK".
URL: /gti/public/init
Ein Aufruf von init liefert zu einem (leeren) InitRequest eine InitResponse, die lediglich allgemeine
Informationen wie Fahrplangültigkeit (Beginn, Ende) und GEOFOX Versions-Informationen
liefert.
Die in der WADL zusätzlich genannten Properties haben derzeit keine Funktion. Für zukünftige APIs ist eine Abfragemöglichkeit für die Properties angedacht, z.B. ob der gerade verwendete Fahrplan die „Weihnachtseigenschaft” hat – ob der derzeitige Fahrplan im Ausnahmeintervall der Weihnachtsfeiertage liegt.
Das Beispiel in den Listings 6 und 7 zeigt den einzig möglichen InitRequest. Dieser ist leer, zurückgegeben werden einige Informationen des aktuellen Fahrplanes.
1{ 2 "returnCode": "OK", 3 "beginOfService": "10.10.2017", 4 "endOfService": "10.12.2017", 5 "id": "03.29.01.21.01", 6 "dataId": "29.74.01", 7 "buildDate": "10.10.2017", 8 "buildTime": "13:14:38", 9 "buildText": "Regelfahrplan 2017" 10}
Die Methode checkName liefert einen vom System verwertbaren, eindeutigen Ort mit allen Details. Dieser kann z.B. anhand von Adressen, Stationen oder POIs gefunden werden. Die allgemeine Funktionsweise kann als Vervollständigung von unvollständigen SDNames angesehen werden. Alle anderen im System auftretenden SDNames sind vollständig. Deren Input ist daher typischerweise der Output von checkName, tatsächlich benötigt werden jedoch nur die Felder id, type sowie combinedName oder name und city.
URL: /gti/public/checkName
Die Methode hat verschiedene Anfragetypen, die gestellt werden können. In Tabelle 4 werden die
Felder vorgestellt. Nicht alle davon werden bei jedem Abfragetyp ausgewertet.
| Feld | Typ |
Beschreibung |
| theName | SDName |
Ein unvollständiger SDName, enthält Suchinformationen |
| maxList | integer |
Maximale Anzahl an Ergebnissen |
| maxDistance | integer |
Für STATION: Maximale Entfernung in Metern, die eine Haltestelle von der angegeben Koordinate entfernt liegen darf (max. 3000m) |
| coordinateType | CoordinateType |
Bezugssystem der Koordinaten, EPSG_4326 (default) oder EPSG_31467. |
| tariffDetails | boolean |
Entscheidet, ob die Response Tarif-Informationen enthält |
| allowTypeSwitch | boolean |
Entscheidet, ob bei Anfragen vom Typ STATION, ADDRESS, POI auch andere Ergebnistypen als in theName angefordert zurückgegeben werden dürfen |
Alle Felder des Typs SDName(Tabelle 6) sind in der WADL als optional gekennzeichnet. Je nach Anfragetyp, der durch das Enum SDType(Tabelle 5) in SDName definiert wird, müssen jedoch bestimmte Felder gefüllt sein. Der Typ TariffDetails wird in Tabelle 7 vorgestellt.
|
Wert SDType / Anfragetyp |
Erforderliche Felder in theName |
Response |
|
STATION |
name und city oder combinedName oder coordinate |
Bei gesetzten Feldern name und city oder combinedName eine Liste aller Haltestellen, die mit dem gesetzten Namen/Stadt übereinstimmen. Falls allowTypeSwitch den Wert true hat, sind auch Adressen und POIs möglich. Bei gesetzter coordinate enthält die Response eine Liste von bis zu 10 Haltestellen, die sich im Umkreis von maxDistance Meter von der angegebenen Koordinate befinden |
|
COORDINATE |
coordinate und optional layer |
Liefert zur angegebenen Koordinate die nächstgelegene Adresse. Die maximale Entfernung beträgt 100 Meter. |
|
ADDRESS |
name und city oder combinedName |
Eine Liste aller Adressen, die mit dem gesetzten Namen/Stadt übereinstimmen. Falls allowTypeSwitch den Wert true hat, sind auch Haltestellen und POIs möglich |
|
POI |
name und city oder combinedName |
Eine Liste aller POIs, die mit dem gesetzten Namen/Stadt übereinstimmen. Falls allowTypeSwitch den Wert true hat, sind auch Haltestellen und Adressen möglich |
|
UNKNOWN |
name und city oder combinedName |
Eine Liste aller übereinstimmender Haltestellen, Adressen und POIs |
| Feld | Typ |
Beschreibung |
| name | string |
Name des Ortes |
| city | string |
Stadt |
| combinedName | string |
Kombinierter Name (aus name und city) |
| id | string |
ID-Nummer des Ortes |
| type | SDType |
Ein Enum, das den Typ des Ortes angibt. Mögliche Werte: UNKNOWN (hier default), STATION, ADDRESS, POI, COORDINATE. Dieses Feld entscheidet über den Anfragetyp von checkName. |
| coordinate | Coordinate |
Koordinaten der geografischen Position |
| layer | integer |
zusätzlich zur Koordinate noch der Layer für unterirdische/überirdische Punkte (ab Version 53). Wird im Fußwegrouting ausgewertet. |
| tariffDetails | TariffDetails |
Tarifrelevante Eigenschaften des Ortes, z.B. in welcher Tarifzone sie liegt (Tabelle 7) |
| serviceTypes | Liste von string |
Liste der hier verkehrenden Verkehrsmittel (z.B: u,bus) |
| hasStationInformation | boolean |
Können zusätzliche Informationen über diese Haltestelle über getStationInformation abgefragt werden? (Seit API Version 28) |
| provider | string |
Information über Provider der Activity-Station (Seit API Version 58) |
| address | string |
Adressangabe, hauptsächlich verwendet für POIs (Seit API Version 59) |
| Feld | Typ |
Beschreibung |
| innerCity | boolean |
Entscheidet die Zugehörigkeit der Haltestelle zum Hamburger Innenstadtbereich |
| city | boolean |
Veraltet: Entscheidet eine Stadtzugehörigkeit für nicht mehr existente Tickets (City-Karte wurde durch Kurzstrecke ersetzt) |
| cityTraffic | boolean |
Entscheidet die Zugehörigkeit zum lokalen Stadtverkehr, wie ihn z.B. Bad Bramstedt oder Stade haben |
| gratis | boolean |
Entscheidet, ob an dieser Haltestelle ausschließlich kostenlose Linien (z.B. Parkshuttlebusse zum Volksparkstadion) verkehren |
| greaterArea | boolean |
Entscheidet die Zugehörigkeit zum HVV-Großbereich |
| shVillageId | int |
Orts-ID im SH-Tarif |
| shTariffZone | int |
SH-Tarif Zone, in der der Ort liegt |
| tariffZones | Liste von int |
Liste der Zonen, in denen der Ort liegt |
| regions | Liste von int |
Veraltet |
| counties | Liste von string |
Liste der Kreise, in denen der Ort liegt |
| rings | Liste von string |
Liste der Ringe, in denen der Ort liegt |
| fareStage | boolean |
Entscheidet, ob hier eine Zahlgrenze vorliegt |
| fareStageNumber | int |
Mehrere Haltestellen können zu einem Zahlgrenzknoten (KTN) zusammenfallen. Dessen ID ist hier angegeben. |
| tariffNames | Liste von string |
Liste der Tarifarten (HVV, SH) |
| uniqueValues | boolean |
Veraltet |
Die CNResponse liefert eine Liste von Orten, genauer: von RegionalSDNames. Der Typ SDName (mit seinen Feldern id, name, city, combinedName, type, coordinate, tariffDetails und serviceTypes) wurde zur RegionalSDName erweitert um die Felder distance und time, die bei einem STATION-Request (zusätzlich zur Liste der Haltestellen in der Nähe einer gegebenen Koordinate) auch deren jeweilige Entfernung in Metern Luftlinie und in Gehminuten übermittelt.
Interessant für den Anfragetyp STATION ist das Feld serviceTypes in SDName, welches seit API Version 16 existiert. Es enthält zu den zurückgegeben Orten die ggf. dort verkehrenden Fahrzeugtypen wie U-Bahn, Schiff und ähnliche.
In Listings 8 und 9 werden Ergebnisse zum Begriff „Christuskirche” angefragt. Eine Haltestelle wird gefunden, die mit ihren Details zurückgegeben wird.
1{ 2 "version":61, 3 "theName":{ 4 "name":"Christuskirche", 5 "type":"UNKNOWN" 6 }, 7 "maxList":1, 8 "coordinateType":"EPSG_4326" 9}
1{ 2 "returnCode": "OK", 3 "results": [ 4 { 5 "name": "Christuskirche", 6 "city": "Hamburg", 7 "combinedName": "Christuskirche", 8 "id": "Master:84902", 9 "type": "STATION", 10 "coordinate": { 11 ... 12 }, 13 "serviceTypes": [ 14 "bus", 15 "u" 16 ], 17 "hasStationInformation": true 18 } 19 ] 20}
URL: /gti/public/getRoute
Die Methode getRoute führt eine Verbindungssuche durch. Die Parameter start, dest und das
optionale via sind dabei vom Typ SDName und am einfachsten dem Output von checkName zu
entnehmen, da dort alle erforderlichen Felder bestimmt werden. Der Request wird in Tabelle 8
vorgestellt.
| Feld |
Typ |
Beschreibung |
| start |
SDName |
Start |
| dest |
SDName |
Ziel (engl. destination) |
| via |
SDName |
Via (die Route soll hierüber verlaufen) |
| time |
GTITime |
Zeit (Bedeutung durch timeIsDeparture) |
| timeIsDeparture |
boolean |
Entscheidet time als Abfahrtszeit (sonst: Ankunftszeit) |
| numberOfSchedules |
integer |
Gewünschte Anzahl auszugebender Fahrten, evtl. werden nur weniger gefunden. Sie verlaufen alle zur gleichen Zeit auf unterschiedlichen Routen. Wenn „0” angegeben wird, wird der Wert Serverseitig auf „1” gesetzt. |
| tariffDetails |
boolean |
Entscheidet, ob die Response Tarif/Ticket-Informationen zur Route enthalten sein soll |
| continousSearch |
boolean |
Garantiert, dass alle Abfahrtszeiten der Routen zu oder nach time (Abfahrtszeit) liegen bzw. alle Ankunftszeiten vor oder zu time (Ankunftszeit) liegen, siehe Anmerkungen unten. Nicht sinnvoll kombinierbar mit schedulesBefore/-After, da durch sie time bereits auf diese Weise interpretiert wird. |
| contSearchByServiceId |
ContSearchByServiceId |
Abhängig von timeIsDeparture wird die nächste/vorherige Route gesucht (Erläuterung in Tabelle 9). Ist dieses Feld gesetzt, so werden continousSearch und die Uhrzeit-Komponente von time ignoriert. (seit API Version 29) |
| coordinateType |
coordinateType |
Bezugssystem der Koordinaten, EPSG_4326 (default) oder EPSG_31467. |
| schedulesBefore |
integer |
Anzahl zusätzlicher Routen, die zeitlich vor der gesuchten optimalen Route starten. Diese können unterschiedlichen Streckenverlauf haben. Nicht kombinierbar mit numberOfSchedules |
| schedulesAfter |
integer |
Anzahl zusätzlicher Routen, die zeitlich nach der optimalen Route starten. Diese können unterschiedlichen Streckenverlauf haben. Nicht kombinierbar mit numberOfSchedules |
| returnReduced |
boolean |
Entscheidet, ob zusätzlich ermäßigte Preise für elektronische Fahrkarten zurückgegeben werden |
| tariffInfoSelector |
Liste aus Tariff InfoSelector |
Gibt an, welche Tarifinformationen zurückgeliefert werden sollen. Siehe dazu einen folgenden Abschnitt |
| penalties |
Penalty |
Siehe dazu einen folgenden Abschnitt |
| returnPartialTickets |
boolean |
Gibt an, ob Fahrkarten für Abschnitte der Gesamtroute berechnet werden sollen |
| realtime |
RealtimeType |
Konfiguriert die Berücksichtigung von Echtzeitinformationen bei der Routenberechnung. (seit API Version 19) |
| intermediateStops |
boolean |
Gibt an, ob auch die Zwischenhalte einer Fahrt zurückgegeben werden sollen. (seit API Version 24) |
| useStationPosition |
boolean |
Default: true. Gibt an, ob die Fahrt auch an Haltestellen in der Nähe der Start- und Zielhaltestelle enden darf. (seit API Version 27) |
| forcedStart |
SDName |
Die Fahrt beginnt hier. Muss eine Haltestelle sein. (seit API Version 27) |
| forcedDest |
SDName |
Die Fahrt beginnt hier. Muss eine Halstestelle sein. (seit API Version 27) |
| toStartBy |
SimpleServiceType |
Gibt an, wie zur Starthaltestelle zu gelangen ist. Überschreibt für die Starthaltestelle den Wert der Penalty ToStartStationBy. Darf nur FOOTPATH oder BICYCLE sein. (seit API Version 27) |
| toDestBy |
SimpleServiceType |
Gibt an, wie zur Endhaltestelle zu gelangen ist. Überschreibt für die Endhaltestelle den Wert der Penalty ToStartStationBy. Darf nur FOOTPATH oder BICYCLE sein. (seit API Version 27) |
| returnContSearchData |
boolean |
Es werden zusätzliche Objekte zurückgegeben, welche die Suche nach einer späteren/vorherigen Route vereinfachen (seit API Version 29) |
| withPaths |
boolean |
Gibt an ob die Path Daten zurückgegeben werden sollen (seit API Version 51) |
| useBikeAndRide |
boolean |
Gibt an, ob Bike and Ride Stationen bei der Suche berücksichtigt werden sollen (seit API Version 58) |
Bei Anfrage mehrerer Verbindungen mittels Setzen des Feldes numberOfSchedules werden die (optimale) Verbindung und evtl. weitere weniger optimale Verbindungen mit abweichender Route zurückgegeben.
Bei Anfrage mehrerer Verbindungen mittels Setzen der Felder schedulesBefore/-After werden (zeitlich nach der optimalen Verbindung) weitere berechnet, die jedoch unterschiedlichen Streckenverlauf haben können. Je nach Bedarf kann eine der beiden Varianten gewählt werden; ein kombiniertes Setzen dieser Felder ist aufgrund der inhaltlichen Verschiedenheit nicht möglich.
Die continousSearch dient kurz gesagt dazu, eine Art Weitersuche umzusetzen. Hierbei ist gemeint,
ausgehend von einer Fahrt die darauffolgende oder vorherige Fahrt zu erhalten. Da die Nutzung und
die Auswirkungen nicht ganz intuitiv sind, sind zum Feld continousSearch und dessen Nutzung
nachfolgende Anmerkungen zu machen:
Es wird im Fall true die erste Fahrt um oder nach der angegebenen Abfahrtszeit genommen,
unabhängig davon, ob bei einer späteren Abfahrt eine kürzere Fahrzeit gefunden wird.
Als Beispiel seien zu einer gewünschten Abfahrtszeit von 10:00 Uhr zwei Routen gegeben: Fahrt 1 startet um 10:00 Uhr und dauert 60 Minuten, Fahrt 2 startet um 10:31 und dauert 30 Minuten (kommt also eine Minute später an und ist deutlich kürzer).
Im Fall continousSearch==true wird Fahrt 1 besser bewertet und die Wartezeit als Reisezeit gezählt, im anderen Fall Fahrt 2.
Damit ist die Möglichkeit geschaffen, zu einer bekannten Fahrt (mit Abfahrt time) die nachfolgende Fahrt zu ermitteln: Man setze continousSearch auf true und wähle als Abfahrtszeit time+1min, ganz analog kann im Fall einer gegebenen Ankunftszeit mit continousSearch auf true und time-1min die vorherige Fahrt gefunden werden.
Dieses Vorgehen stellt sich im Bezug auf Echtzeit jedoch nicht als komplett fehlertolerant dar. Man stelle sich das Beispiel vor, bei dem eine Fahrt eine Verspätung hat. Wendet man auf diese Fahrt das oben beschriebene Verfahren an, kann es dazu kommen, dass eben genau diese Fahrt als nachfolgende Fahrt ermittelt wird, da die Abfahrt durch die Echtzeit verschoben ist, ein Kreisschluss kann entstehen.
Aus diesem Grund kann man ab Version 29 auch das Feld returnContSearchData setzen. Die in
Schedule.contSearchBefore und Schedule.contSearchAfter zurückgegebenen Objekte eignen
sich dann, um die vorherige, bzw. nächste Fahrt zu ermitteln. Diese Methode ist in Bezug
auf Echtzeit fehlertoleranter als continousSearch, welche im Fall von Verspätungen
Probleme hat die nächst-spätere Route zu ermitteln. Da das Verfahren neben der Nutzung des
Schedule.contSearchBefore- bzw. Schedule.contSearchAfter-Objekts auch von der richtigen
Nutzung des TimeIsDeparture-Feldes abhängig ist, soll folgende Erklärung das Vorgehen weiter
erklären:
Möchte man nach vorherigen Fahrten suchen, setzt man das Schedule.contSearchBefore als
ContSearchByServiceId ein, sowie timeIsDeparture=false. Umgekehrt, wenn man die
nachfolgende Fahrt bekommen möchte, setzt man das Schedule.contSearchAfter als
ContSearchByServiceId ein, sowie timeIsDeparture=true.
Die Liste aus TariffInfoSelector im Feld tariffInfoSelector gibt an, welche Tarife und Kartenarten für jedes Schedule zurückgegeben werden sollen. Der Typ TariffInfoSelector wird in Tabelle 10 vorgestellt.
| Typ |
Typ |
Ergebnis |
| tariff |
String |
Name des Tarifs (hvv, sh, all). Der Wert all bezieht die Filterangaben auf alle Tarife. Wird nur der hvv-Tarif gefiltert und die Verbindung hat nur SH-Tarif, dann werden alle Tickets zurückgegeben. Gilt analog bei Filtern von SH, wenn Verbindung nur hvv. (default: hvv) |
| tariffRegions |
Boolean |
Entscheidet, ob Tarifbereiche (-zonen, -ringe, -kreise) zurückgegeben werden (default: true) |
| kinds |
Liste aus integer |
Die zurückzugebenden Kartenarten. Bei einer leeren Liste von kinds und groups werden alle gültigen Karten zurückgegeben. |
| groups |
Liste aus integer |
Die zurückzugebenden Kartengruppen. Bei einer leeren Liste von kinds und groups werden alle gültigen Karten zurückgegeben. Seit API Version 54. |
| blacklist |
Boolean |
Entscheidet, ob Tickets gewhitelistet oder geblacklistet werden sollen. Whitelisting: Gibt alle Tickets zurück, die entweder den kinds oder den groups entsprechen. Blacklisting: Gibt alle Tickets zurück, die weder den kinds noch den groups entsprechen. (default: false) Seit API Version 54. |
Die Liste der verfügbaren HVV-Karten (kinds) hier ist nur exemplarisch. Sie ist auf dem Stand von Juli 2012 in der Tabelle 11 aufgeführt.
| ID |
Kartenart | ID |
Kartenart |
| 1 |
Einzelfahrt | 52 |
Wochenkarte |
| 2 |
Einzelkarte für Kinder | 70 |
9-Uhr-Senioren-Monatskarte |
| 11 |
Ganztageskarte | 71 |
9-Uhr-Senioren-Abo-Karte |
| 21 |
9-Uhr-Tageskarte | 72 |
Kinder-Monatskarte |
| 22 |
9-Uhr-Tageskarte Kind | 73 |
Kinder-Abonnementskarte |
| 23 |
9-Uhr-Gruppenkarte | 80 |
Schüler-Monatskarte |
| 31 |
3-Tage-Karte | 82 |
Schüler-Monatsnebenkarte |
| 50 |
Allgemeine Monatskarte | 81 |
Schüler-Abonnementskarte |
| 51 |
Allgemeine Abonnementskarte | 83 |
Schüler-Abo-Nebenkarte |
| 60 |
CC-Monatskarte | 90 |
Studierende/Azubi-Monatskarte |
| 61 |
CC-Abonnementskarte | 91 |
Studierende/Azubi-Abo-Karte |
Die Methode getRoute findet die optimale Route und führt dazu im Hintergrund eine mathematische Minimierung der Bewertung verschiedener Routen hinsichtlich ihres Verlaufes und ihrer Eigenschaften aus. Es wird jene Route zurückgegeben, die die beste Bewertung hat, eine typische Bewertung ist die Dauer. Eine Route wird jedoch nicht ausschließlich anhand ihrer Dauer gemessen. Für ungewünschte Eigenschaften einer Route fließen zusätzliche Faktoren (Bestrafungen, engl. penalties) in die Bewertung ein. Für den Wunsch „bitte Schiff vermeiden” wird bei einer diese Forderung verletzenden Route jede Minute auf einem Schiff mit einem Strafffaktor multipliziert, so dass die kürzeste Route (bei verfügbaren Alternativen) keinen Abschnitt per Schiff enthalten wird. Über das optionale Feld penalties kann also die Routenfindung zuungunsten verschiedener Eigenschaften beeinflusst werden; auch ein Einfluss „zugunsten” ist möglich, da die Penalties prinzipiell auch negativ sein können – negative Straffaktoren fallen positiv ins Gewicht, wie z.B. im Falle von DesiredType. Die Penalities werden in Tabelle 12 aufgeführt.
| Penalty Name | Typ d. Value |
Beschreibung |
| ChangeEvent | Integer |
Bewertung von Umsteigen |
| ExtraFare | Integer |
Bewertung von zuschlagspflichtigen Fahrten |
| Walker | Integer |
Bewertung von Fußwegen, vgl. AnyHandicap |
| AnyHandicap | Integer |
Bewertung von Wegerschwernissen Mobilität/des Fahrgastes (z.B. Treppen, lange Fußwege), vgl. Walker |
| ToStartStationBy | Integer |
Art der Fortbewegung zur Haltestelle |
| TimeRange | Integer |
Gibt den Faktor zur Bewertung von Wartezeit als Reisezeit an, siehe Feld continousSearch im GRRequest |
| ForVisitors | Integer |
Gibt an, ob der Fahrgast ortsfremd ist und längere Umsteigezeiten gewünscht sind |
| DesiredType | String |
Bewertung einzelner Verkehrsmittel |
| DesiredLine | String |
Präferenz von Linien (geplant nach API Verison 16) |
Man kann sich vorstellen, dass einige der Penalties so etwas wie Strafminuten darstellen; dies wird deutlich bei der Frage, welchen Umweg man zur Vermeidung von z.B. eines Umsteigens in Kauf nehmen möchte. Dies gilt jedoch nicht allgemein, so dass diese Werte lediglich symbolisch zu betrachten sind.
Die in Tabelle 13 beschriebenen Key/Value-Paare der Penalties sind daher bindend, nicht genannte Zwischenabstufungen sind nicht zulässig.
|
Penalty |
Werte |
Bedeutung der Werte |
Bemerkung |
|
ChangeEvent
|
0 |
gern,
wenn
schneller |
Default: normal, 4 |
|
ExtraFare
|
0 |
gern,
wenn
schneller |
Default: normal, 10 |
|
Walker
|
0 |
gern,
wenn
schneller |
Default: normal, 1 |
|
AnyHandicap
|
-1 |
gut
zu
fuß |
Default: normal, 0 |
|
ToStartStationBy
|
0 |
zu
Fuß |
Default: zu Fuß, 0 |
|
TimeRange
|
10 |
sehr
groß |
Default:
normal,
30 |
|
ForVisitors
|
0 |
nein |
Default:nein, 0 |
|
DesiredType
|
-10 |
unbedingt |
Default:
0 |
|
DesiredLine
|
2 |
bevorzugen |
kein Default. Kombinationen wie {"name":"DesiredLine", "value":"u2,s1:1"} sind möglich. |
|
DesiredCarrier
|
2 |
bevorzugen |
Default:
neutral,
0 |
In Tabelle 14 sind die möglichen Fahrzeugtypen für die Penalty DesiredType aufgelistet.
|
Wert |
Bedeutung |
|
bus |
Bus |
|
ship |
Schiff |
|
u |
U-Bahn |
|
s |
S-Bahn |
|
r |
Regionalbahnen (R-Bahn) |
|
train |
alle Bahnen |
|
fasttrain&extrafasttrain |
IC/EC/ICE/TGV |
|
extrafasttrain |
ICE/TGV |
|
callable |
Anruf-Sammel-Taxi |
|
ast |
Anruf-Sammel-Taxi. Alias für callableAnruf-Sammel-Taxi |
|
rb |
Regionalbahn (nicht Regionalexpress). Bezeichnung für Linien die mit Rxx oder RBxx beginnen, wobei xx für eine Zahl steht. |
|
re |
Regionalexpress |
|
normalbus |
Alle Busse, ausser ASTs, Fernbussen oder Schnellbussen. |
|
fastbus |
Schnellbus |
|
longdistancebus |
Fernbus |
In der folgenden Liste sind die möglichen Betreiber für die Penalty DesiredCarrier aufgelistet. Achtung: Die möglichen Werte aus dieser Liste können sich mit jeder Datenlieferung ändern.
|
AKN |
Autokraft |
DB-Regio |
Dahmetal |
|
EVB |
EVM |
Fernzug |
Globetrotter |
|
HHA |
HL |
Hadag |
KVIP |
|
LVG |
metronom |
MZH |
nordbahn |
|
PVG |
RB S-H |
S-Bahn |
Storjohann |
|
VHH |
VOG |
Auf der Internetseite http://geofox.hvv.de kann ein persönlicher Fahrplan angefragt werden, wie es auch mittels getRoute möglich ist. In Abb. 3 sind die beiden Möglichkeiten derselben Anfrage gegenüberstellt.
In Tabelle 15 wird beschrieben, welche Optionenauswahl zu welchen zusätzlichen Penalties führt.
|
Optionen |
Penalties |
|
Beste
Verbindung |
AnyHandicap=-1 |
|
Beste
Verbindung |
Default, keine extra Penalties |
|
Beste
Verbindung |
AnyHandicap=1 |
|
Schnellste
Verbindung |
AnyHandicap=-1
|
|
Schnellste
Verbindung |
ChangeEvent=0
|
|
Schnellste
Verbindung |
AnyHandicap=1
|
|
Rollstuhl |
ExtraFare=0 |
Die folgende Tabelle beschreibt einen GRResponse
| Feld | Typ |
Beschreibung |
| schedules | Liste aus Schedules |
Liste von Routenergebnissen basierend auf Plandaten |
| realtimeSchedules | Liste aus Schedules |
Liste von Routenergebnissen basierend auf Echtzeitdaten |
| realtimeAffected | SDName |
Gibt an ob das angegebene Suchergebnis durch Echtzeitdaten beeinflusst wurde. |
| individualTrack | SDName |
Informationen über den direkten Fuß- oder Fahrradweg als Vergleichswert zur ÖPNV-Verbindung |
Ein Schedule erweitert BaseSchedule um eine Liste von scheduleElements. Eine Zusammenfassung aller Felder steht in Tabelle 17.
| Feld | Typ |
Beschreibung |
| routeId | Integer |
Eine ID zur Identifikation der Route |
| start | SDName |
Wiederholung von Start |
| dest | SDName |
Wiederholung von Ziel |
| time | Integer |
Die gesamte Reisedauer, inkl. Umstiege und Fußwege zu/ab Start/Ziel |
| plannedDepartureTime | DateTime |
Die geplante Abfahrtszeit am Start |
| plannedArrivalTime | DateTime |
Die geplante Ankunftszeit am Ziel |
| realDepartureTime | DateTime |
Die tatsächliche Abfahrtszeit am Start |
| realArrivalTime | DateTime |
Die tatsächliche Ankunftszeit am Ziel |
| footpathTime | Integer |
Die Dauer aller Fußwege inkl. Umstiege |
| tickets | Liste aus Ticket |
Eine Liste aller für diese Route gültigen Tickets. Zu jedem Typ ein Ticket mit minimal notwendigem Level. Veraltet seit API 13. |
| scheduleElements | Liste aus ScheduleElement |
Liste der Verbingungsabschnitte. Seit API Version 12 sind auch Umsteigefußwege eigene Abschnitte und damit ScheduleElements |
| tariffInfos | Liste aus TariffInfo |
Ggf. eine Liste von Tarifinformationen, abhängig vom tariffInfoSelector im Request (seit API 13) |
| contSearchBefore | ContSearchByServiceId |
Ein Objekt, das gegebenenfalls durch Setzen von GRRequest.returnContSearchData ermittelt werden kann. (seit API 29) |
| contSearchAfter | ContSearchByServiceId |
Ein Objekt, das gegebenenfalls durch Setzen von GRRequest.returnContSearchData ermittelt werden kann. (seit API 29) |
Möchte man das zurückgegebene Schedule.contSearchBefore/After-Objekt in einem neuen Request
für GRRequest.contSearchByServiceId verwenden, so muss
GRRequest.timeIsDeparture auf false/true gesetzt werden. Aufgrund der zusätzlichen
Informationen in GRRequest.contSearchByServiceId wird die Uhrzeit-Komponente von
GRRequest.time ignoriert. Nur die Datums-Komponente wird genutzt.
Die Felder von ScheduleElement (der GRResponse) werden in Tabelle 18 beschrieben.
| Feld | Typ |
Beschreibung |
| from | JourneySDName |
Starthaltestelle inklusive der Abfahrtszeit und Gleisinformationen (platform) |
| to | JourneySDName |
Zielhaltestelle inklusive Ankunftszeit und Gleisinformationen (platform) |
| line | Service |
Das Verkehrsmittel |
| paths | Liste aus Path |
Eine Liste von möglichen Streckenverläufen. Jeder Path hat nur ein Feld track, dies ist eine Liste aus Coordinate |
| attributes | Liste aus Attribute |
Ein Attribute besteht aus dem String value (enthält den Nachrichtentext) und einer Liste von types, letzteres nimmt z.B. für Linieninformationen („Nach 19 Uhr kann auch zwischen Haltestellen ausgestiegen werden”) den Wert NORMAL an. Für Fahrplanderänderungen („Straßenbauarbeiten bewirken Fahrtverzögerungen”, „Schienenersatzverkehr”) hat es den Wert ANNOUNCEMENT (nur bis Version 54). Seit Version 43 gibt es das Feld id vom Typ String, welches eine eindeutige ID enthalten kann, bspw. für Announcements. Für den Fall, dass die Echtzeit-Verspätungszeiten ungenau sind, gibt es noch die Attribut-Typen TRAFFIC_JAM, TECHNICAL_PROBLEM(z.B. Bei der Übermittlung der Daten is ein Problem aufgetreten, keine aktuellen Informationen vorhanden), DISPOSITIVE_ACTION(z.B. Zur Sicherung eines Anschlusses wartet das Fahrzeug), MISSING_UPDATE(z.B. eine Prognose liegt vor, kann aber Aufgrund von Kommunikationsstörungen nicht aktualisiert werden.). Ab Version 55 werden Attribute des Typs ANNOUNCEMENT nicht mehr ausgeliefert. |
| announcements | Liste aus Announcement |
Announcements werden in Tabelle 45 beschrieben. Announcements werden ausschließlich in diesem Feld ausgeliefert, und nicht mehr als Attribute des Typs ANNOUNCEMENT. Falls das Startdatum des ScheduleElement innerhalb des publication-Zeitraums des Announcements, aber nicht innerhalb eines validities-Zeitraums des Announcements liegt, so handelt es sich um eine Vorankündigung. Ab Version 55. |
| extra | boolean |
Fahrt ist Verstärkerfahrt (seit API Version 19) |
| cancelled | boolean |
Fahrt fällt aus (seit API Version 19) |
| intermediateStops | Liste aus JourneySDName |
Eine Liste der Zwischenhalte. Um die Daten klein zu halten, werden weniger wichtige Informationen z.B. zum Tarif oder zur Ankunftszeit weggelassen. (seit API Version 24) |
| vehicles | Liste aus Vehicle |
Eine Liste der Fahrzeuge, die diese Fahrt durchführen, optional (seit API Version 57) |
| shopInfo | Liste aus ShopInfo |
Informationen über Shops zum Kauf von Fahrkarten für diesen Streckenabschnitt |
Die Felder von ContSearchByServiceId werden in Tabelle 19 beschrieben.
| Feld | Typ |
Beschreibung |
| serviceId | integer |
Die Service-Id des Fahrzeugs des ersten/letzen gefahrenen Streckenabschnitts |
| lineKey | String |
Die Linien-Id des Fahrzeugs des ersten/letzten gefahrenen Streckenabschnitts |
| plannedDepArrTime | GTITime |
Die Uhrzeit in Minuten, zu der die Start-/Zielhaltestelle nach Fahrplan angefahren werden sollte. |
| additionalOffset | integer |
Die Dauer des Fußwegs/Fahrradwegs zur ersten/letzten Haltestelle. Ist timeIsDeparture gesetzt, so sollte additionalOffset 0 oder negativ sein. |
Ein Service (in ScheduleElement) speichert das verwendete Verkehrsmittel. Es wird in Tabelle 53 beschrieben.
| Feld | Typ |
Beschreibung |
| id | string |
optionale ID für diesen Service |
| name | string |
Name, optional |
| direction | string |
Richtung, optional |
| directionId | integer |
Id für die Richtung, optional. Hin- (1) und Rückrichtung (6) |
| type | ServiceType |
Ein ServiceType enthält drei Felder: Das Enum SimpleServiceType (mit den Werten BUS, TRAIN, SHIP, FOOTPATH, BICYCLE, AIRPLANE, CHANGE, CHANGE_SAME_PLATFORM, ACTIVITY_BIKE_AND_RIDE) klassifiziert den Typ des Service, zwei Strings shortInfo und longInfo beschreiben ihn |
| carrierNameShort | string |
Kurzname des Betreibers des Verkehrsmittels, optional |
| carrierNameLong | string |
Name des Betreibers des Verkehrsmittels, optional |
Der Typ JourneySDName (in ScheduleElement) erweitert den bei der Besprechung des CNRequest vorgestellten SDName (mit seinen Feldern name, city, combinedName, id, type, coordinate, tariffDetails, serviceTypes). Die Erweiterung zum JourneySDName besteht aus den Feldern in Tabelle 21.
| Feld | Typ |
Beschreibung |
| arrTime | GTITime |
planmäßige Ankunftszeit an diesem JourneySDName, optional |
| depTime | GTITime |
planmäßige Abfahrtszeit an diesem JourneySDName, optional |
| attributes | Liste von Attribute |
Liste der Attribute des Ortes, siehe Tabelle zu scheduleElement |
| platform | string |
Das Gleis, an dem das Verkehrsmittel verkehrt |
| arrDelay | int |
Ankunfts-Verspätungszeit in Sekunden (seit API Version 19) |
| depDelay | int |
Abfahrts-Verspätungszeit in Sekunden (seit API Version 19) |
| extra | boolean |
Dieses Flag wird gesetzt wenn die angegebene Fahrt hier außerplanmäßig zusätzlich hält. (seit API Version 19) |
| cancelled | boolean |
Dieses Flag wird gesetzt wenn die angegebene Fahrt aufgrund aktueller Fahrplanabweichungen nicht an dieser Haltstelle hält. (seit API Version 19) |
| realtimePlatform | string |
Das Gleis, dass als Echtzeitinformation zu diesem Halt übermittelt wurde. |
Der Typ Vehicle (in ScheduleElement) beschreibt ein konkretes Fahrzeug, welches einzeln oder im Verbund eine Fahrt durchführt.
Der Typ TariffInfo (der GRResponse) wird in Tabelle 23 beschrieben.
| Feld |
Typ |
Beschreibung |
| tariffName |
String |
Name des Tarifes |
| tariffRegions |
Liste von TariffRegionInfo |
Die TariffRegionInfo enthalten je ein Enum TariffRegionType (enums ZONE, GH_ZONE, RING, COUNTY) sowie eine Liste von TariffRegionList, die eine Liste ihres einzigen Feldes regions (String) speichert. Anschaulich speichert TariffRegionInfo den Tarifbereich und die durchfahrenen Tarifzonen (Zonen, Ringe, Kreise). Weil einige Haltestellen zu zwei Tarifzonen gehören (zwischen zwei Tarifzonen liegen), sind die durchfahrenen Tarifzonen einer Fahrt mehrdeutig – alle möglichen Interpretationen (Tarifzonenlisten) werden hier als Liste gespeichert. |
| extraFareType |
Enum extraFareType |
Das Enum gibt Auskunft über die Notwendigkeit eines erste-Klasse/Schnellbus-Zuschlags mit den Werten NO (zuschlagsfrei, default), POSSIBLE (Zuschlag möglich), REQUIRED (Zuschlagszahlung erforderlich). |
| ticketInfos |
Liste von TicketInfo |
Eine Liste der gültigen Tickets, siehe die folgende Tabelle |
| ticketRemarks |
string |
Weitere Informationen zum Ticket, z.B. eine beschränkte Gültigkeit für nur einen Teilabschnitt der Strecke (seit API 18). Ist dem Fahrgast zwingend mitzuteilen, da dies die Gültigkeit der Preisauskunft einschränkt |
TicketInfo Objekte sind aufgebaut wie in Tabelle 24 beschrieben. Die Felder tariffGroupID und tariffGroupLabel existieren zur strukturierteren Darstellung der Kartenarten im Client; dadurch sind z.B. HVV-Tickets gruppierbar in die Kategorien Monatskarte, CC-Karte, ermäßigte Karte usw.
| Feld | Typ |
Beschreibung |
| tariffKindID | integer |
ID der Kartenart |
| tariffKindLabel | string |
Name der Kartenart |
| tariffLevelID | integer |
ID der Tarifstufe |
| tariffLevelLabel | string |
Name der Tarifstufe |
| viaPathId | string |
ID des Überwegs, falls anwendbar (z.B. bei SH-Tarifen) |
| tariffGroupID | integer |
ID der Tarifgruppe |
| tariffGroupLabel | string |
Name der Tarifgruppe |
| basePrice | double |
Basispreis der Fahrkarte ohne Zuschlag |
| extraFarePrice | double |
Zuschlagspreis. Diese Feld ist leer, wenn in der TariffResponse das Feld extraFareType auf NO steht. |
| reducedBasePrice | double |
Seit
API
Version
16
können
zusätzlich
reduzierte
Preise
für
elektronische
Fahrkarten
zurückgegeben
werden,
dies
erfordert
im
Request
das
Flag
returnReduced |
| reducedExtraFarePrice | double |
|
| currency | string |
Währung (default: EUR) |
| regionType | Enum |
Dieser Typ von Bereichsinformationen wird (ab API Version 14) für dieses Ticket zusätzlich benötigt. Werte: ZONE, GH_ZONE, RING, COUNTY |
| notRecommended | boolean |
Wenn auf true gesetzt, dann wird diese Karte nicht empfohlen, da es günstigere Alternativen gibt. |
| shopLinkRegular | string |
Definiert den offiziellen Link zum bestellen/kaufen des regulären Tickets. |
| shopLinkExtraFare | string |
Definiert den offiziellen Link zum bestellen/kaufen des Zuschlagtickets. |
| startStationId | string |
ID der Starthaltestelle. Aktuell nur bei SH-Tarif benutzt. |
| endStationId | string |
ID der Zielhaltestelle. Aktuell nur bei SH-Tarif benutzt. |
| baseTicketID | string |
ID der Ticket-Variante 2. Klasse ohne Rabatt. Seit API-Version 60. |
| reducedBaseTicketID | string |
ID der Ticket-Variante 2. Klasse mit Rabatt. Im Request muss returnReduced gesetzt sein. Seit API-Version 60. |
| extraFareID | string |
ID der Ticket-Variante 1. Klasse ohne Rabatt. Seit API-Version 60. |
| reducedExtraFareTicketID | string |
ID der Ticket-Variante 1. Klasse mit Rabatt. Im Request muss returnReduced gesetzt sein. Seit API-Version 60. |
Zur Konfiguration der Berücksichtigung von Echtzeitinformationen bei der Routensuche gibt es den optionalen Request Paramter realtime vom Typ RealtimeType. Über diesen Paramter kann der Client steuern, ob er ein Ergebnis auf Basis von Echtzeitinformationen (REALTIME) oder auf Basis von Plandaten (PLANDATA) erhalten möchte. In beiden Fällen wird das Suchergebnis mit Verspätungs-, Verstärker- und Ausfallinformationen angereichert. Der Unterschied besteht darin, dass für die Suche der optimalen Route Echtzeitinformationen berücksichtigt werden. So kann bei einer Suche auf Basis von Plandaten auch ein Ergebnis berechnet werden, dass aufgrund von verpassten Anschlüssen durch Verspätungen so nicht gefahren werden kann. Zusätzlich zu diesen beiden Varianten gibt es noch eine automatische Einstellungsmöglichkeit (AUTO). In diesem Fall wird sowohl das Plan- als auch das Echtzeitergebnis geliefert, wenn diese beiden Ergebnisse sich von einander unterscheiden. Ob sich das Echtzeitergebnis vom Planergebnis unterscheidet kann dem Response-Flag realtimeAffected entnommen werden. (siehe auch Abschnitt 1.8).
Es wird angefragt, vom Rosenhof in Ahrensburg über Kellinghusenstraße zur Stadthausbrücke zu fahren. Dabei wird vom regionalen Datenfilter Gebrauch gemacht und die Variable filterType auf HVV_LISTED gesetzt.
Die Antwort beinhaltet mehrere Routen, von denen nur jene mit "routeId": 0 hier angegeben ist. In einer Route werden zunächst Start und Ziel wiederholt, es wird die Reise- und Fußwegzeit ausgegeben sowie das günstigste Ticket, das für diese Reise gültig ist, benannt. Danach werden die Reiseabschnitte (scheduleElements) als Liste ausgegeben. Sie beinhalten from und to (welche SDNames samt Details sind), danach folgt das Feld line, das die Fortbewegungsart zwischen from und to angibt – dies kann eine Linie (z.B. U2), aber auch ein Fußweg oder Umsteigeweg sein.
In jedem scheduleElement ist zuletzt der path genannt. Dies ist eine Liste der Koordinaten, anhand derer das scheduleElement am Client gezeichnet werden kann. In den scheduleElement können auch Attribute enthalten sein, von denen vielleicht der Typ ANNOUNCEMENT hervorzuheben ist. In diesem Feld sind Bekanntgaben des Betreibers zum scheduleElement (hier: S3) vermerkt, z.B. Umleitungen und Schienenersatzverkehr. Diese werden zwar in der Regel schon bei der Routenfindung berücksichtig, jedoch kann natürlich eine Verzögerung auftreten, bis eine temporäre Änderung am Streckennetz (wie eine Umleitung nach einem Unfall) ihren Weg in die Daten gefunden hat.
1{ 2 "version": 61, 3 "language": "de", 4 "start": { 5 "name": "Rosenhof", 6 "city": "Ahrensburg", 7 "combinedName": "Ahrensburg, Rosenhof", 8 "id": "Master:35009", 9 "type": "STATION", 10 "coordinate": { 11 "x": 9.93454, 12 "y": 53.552405 13 } 14 }, 15 "dest": { 16 "name": "Stadthausbrücke", 17 "city": "Hamburg", 18 "combinedName": "Stadthausbrücke", 19 "id": "Master:11952", 20 "type": "STATION", 21 "coordinate": { 22 "x": 9.93454, 23 "y": 53.552405 24 } 25 }, 26 "via":{ 27 "name": "Kellinghusenstraße", 28 "city": "Hamburg", 29 "id": "Master:90904", 30 "type": "STATION", 31 "coordinate": { 32 "x": 9.93454, 33 "y": 53.552405 34 } 35 }, 36 "time": { 37 "date": "17.10.2017", 38 "time": "13:10" 39 }, 40 "timeIsDeparture": true, 41 "schedulesBefore": 1, 42 "schedulesAfter": 2, 43 "realtime": "REALTIME" 44}
1{ 2 "returnCode": "OK", 3 "realtimeSchedules": [ 4 { 5 "routeId": 0, 6 "start": { 7 "name": "Rosenhof", 8 "city": "Ahrensburg", 9 "combinedName": "Ahrensburg, Rosenhof", 10 "id": "Master:35009", 11 "type": "STATION", 12 "coordinate": {...}, 13 "serviceTypes": [ 14 "bus" 15 ], 16 "hasStationInformation": false 17 }, 18 "dest": { 19 "name": "Stadthausbrücke", 20 "city": "Hamburg", 21 "combinedName": "Stadthausbrücke", 22 "id": "Master:11952", 23 "type": "STATION", 24 "coordinate": {...}, 25 "serviceTypes": [ 26 "s" 27 ], 28 "hasStationInformation": true 29 }, 30 "time": 81, 31 "footpathTime": 6, 32 "tickets": [ 33 { 34 "price": 3.2, 35 "type": "Einzelkarte HVV (EUR)", 36 "level": "Hamburg AB", 37 "tariff": "HVV" 38 } 39 ], 40 "scheduleElements": [ 41 { 42 "from": { 43 "name": "Rosenhof", 44 "city": "Ahrensburg", 45 "combinedName": "Ahrensburg, Rosenhof", 46 "id": "Master:35009", 47 "type": "STATION", 48 "coordinate": {...}, 49 "serviceTypes": [ 50 "bus" 51 ], 52 "hasStationInformation": false, 53 "depTime": { 54 "date": "17.10.2017", 55 "time": "13:19" 56 } 57 }, 58 "to": { 59 "name": "U Ahrensburg West", 60 "city": "Ahrensburg", 61 "combinedName": "U Ahrensburg West", 62 "id": "Master:34009", 63 "type": "STATION", 64 "coordinate": {...}, 65 "serviceTypes": [ 66 "bus", 67 "u" 68 ], 69 "hasStationInformation": false, 70 "arrTime": { 71 "date": "17.10.2017", 72 "time": "13:45" 73 } 74 }, 75 "line": { 76 "name": "569", 77 "direction": "Ahrensburg, Schulzentrum Am Heimgarten", 78 "origin": "Ahrensburg, Rosenhof", 79 "type": { 80 "simpleType": "BUS", 81 "shortInfo": "Bus", 82 "longInfo": "Niederflur Stadtbus", 83 "model": "Niederflur Stadtbus" 84 }, 85 "id": "VHH:569_VHH", 86 "carrierNameShort": "VHH", 87 "carrierNameLong": "Verkehrsbetriebe Hamburg-Holstein GmbH" 88 }, 89 "paths": [ 90 { 91 "track": [ 92 { 93 "x": 10.240837, 94 "y": 53.683063 95 }, 96 { 97 "x": 10.240822, 98 "y": 53.683063 99 }, 100 ... 101 ] 102 } 103 ], 104 "attributes": [ 105 { 106 "value": "Test-Meldung für das Gesamtnetz", 107 "types": [ 108 "ANNOUNCEMENT" 109 ] 110 } 111 ], 112 "serviceId": 60848 113 }, 114 { 115 "from": { 116 "name": "U Ahrensburg West", 117 "city": "Ahrensburg", 118 "combinedName": "U Ahrensburg West", 119 "id": "Master:34009", 120 "type": "STATION", 121 "coordinate": {...}, 122 "serviceTypes": [ 123 "bus", 124 "u" 125 ], 126 "hasStationInformation": false, 127 "depTime": { 128 "date": "17.10.2017", 129 "time": "13:45" 130 } 131 }, 132 "to": { 133 "name": "Ahrensburg West", 134 "city": "Ahrensburg", 135 "combinedName": "Ahrensburg West", 136 "id": "Master:34900", 137 "type": "STATION", 138 "coordinate": {...}, 139 "serviceTypes": [ 140 "bus", 141 "u" 142 ], 143 "hasStationInformation": true, 144 "arrTime": { 145 "date": "17.10.2017", 146 "time": "13:47" 147 } 148 }, 149 "line": { 150 "name": "Umstiegsfußweg", 151 "type": { 152 "simpleType": "CHANGE" 153 } 154 } 155 }, 156 ... 157 ] 158 } 159 ], 160 "individualTrack": { 161 "time": 371, 162 "length": 25562, 163 "type": "FOOTPATH" 164 } 165}
Die Methode departureList liefert die Abfahrten an einer gegebenen Haltestelle in einem gegebenen Zeitintervall.
URL: /gti/public/departureList
Die Felder des Requests sind in Tabelle 25 gelistet.
| Feld | Typ |
Beschreibung |
| station | SDName |
Haltestelle, für die Abfahrten gesucht werden |
| stations | Liste von SDName |
Haltestellen, für die Abfahrten gesucht werden. Von station oder station muss mindestens ein Feld gefüllt sein. |
| time | GTITime |
Zeitpunkt, ab dem Abfahrten gesucht werden |
| maxList | integer |
Maximale Anzahl an zurückzugebenden Abfahrten |
| maxTimeOffset | integer |
Länge des Zeitintervalls ab time, in dem Abfahrten gesucht werden |
| allStationsInChangingNode | boolean |
Falls die station ein Umsteigeknoten (changingNode) ist und damit ggf. mehrere Haltestellen hat, entscheidet dieses Feld, ob Abfahrten aller Haltestellen dieses Knotens gemeint sind. |
| returnFilters | boolean |
Steuert ob eine Liste von FilterEntrys zurück gegeben werden soll (siehe 2.4.3). (seit API Version 20) |
| filter | Liste von FilterEntry |
Ist dieses Feld gefüllt, wird eine gefilterte Liste von Departures ausgegeben (siehe 2.4.3). (seit API Version 20) |
| serviceTypes | Liste von FilterServiceType |
Ist dieses Feld gefüllt, wird die Ergebnisliste anhand von Verkehrsmitteln gefiltert. (seit API Version 22) |
| useRealtime | boolean |
Gibt an ob Echtzeitinformationen berücksichtigt werden sollen. |
| coordinateType | coordinateType |
Bezugssystem der Koordinaten, EPSG_4326 (default) oder EPSG_31467. (seti API Version 61) |
Die Felder der DLResponse sind in Tabelle 26 gelistet.
| Feld | Typ |
Beschreibung |
| time | GTITime |
Referenzzeit für diese Abfahrtstafel |
| departures | Liste von Departures |
Liste der Abfahrten |
| filter | Liste von DLFilterEntry |
Liste mit sinnvollen Filtermöglichkeiten für die abgefragte Haltestelle (siehe 2.4.3) |
| serviceTypes | Liste von FilterServiceType |
Liste der Verkehrsmittel die an der angegebenen Haltestelle abfahren/ankommen |
Die Felder der Departure sind in Tabelle 27 gelistet.
| Feld | Typ |
Beschreibung |
| line | Service |
Name, direction, type und ID des Verkehrsmittels, siehe GRResponse |
| direction | integer |
Die Richtungs-ID der Fahrt (1 für vorwärts, 6 für rückwärts) (seit API Version 39) |
| timeOffset | integer |
Die Minuten zwischen time aus dem Request und der Abfahrt |
| station | SDName |
Die Haltestelle des Umsteigeknotens, von dem aus diese Fahrt abfährt. Dieses Feld wird nur verwendet im Fall allStationsInChangingNode==true |
| stopPoint | SDName |
Der Mast / das Gleis der Station, von dem aus diese Fahrt abfährt. (seit API Version 61) |
| serviceId | integer |
Eine eindeutige ID dieser Fahrt |
| platform | string |
Gleisinformationen (seit API Version 11) |
| delay | int |
Verspätungszeit in Sekunden (seit API Version 19) |
| extra | boolean |
Fahrt ist Verstärkerfahrt (seit API Version 19) |
| cancelled | boolean |
Fahrt fällt aus (seit API Version 19) |
| realtimePlatform | string |
Das Gleis, dass als Echtzeitinformation zu dieser Fahrt übermittelt wurde. (seit API Version 21) |
| attributes | Attribute |
Zusätzliche textuelle Informationen zu dieser Fahrt (seit API Version 23) |
Die Liste der zurückgegebenen Departures kann serverseitig gefiltert werden. Im DLRequest gibt es dafür zwei Filtermöglichkeiten. Über das Feld filter kann auf einzelne Linien/Richtungen gefiltert werden. Ein FilterEntry enthält dabei die folgenden Felder.
| Feld | Typ |
Beschreibung |
| serviceID | String |
Linien-ID: Filtert die Liste anhand von Linien. |
| stationIDs | Liste von String |
Filtert die Liste anhand einer Richtung auf der angegebenen Linie. |
| serviceName | String |
Anzuzeigender Linienname (Wird im DLRequest nicht benötigt) |
| label | String |
Anzuzeigender Richtungstext (Wird im DLRequest nicht benötigt) |
Ein gültiger FilterEntry muss mindestens das Feld serviceID gefüllt haben. Wird zusätzlich das Feld stationIDs gefüllt, werden nur Fahrten zurückgegeben, die über mindestens eine der angegebenen Haltestellen führen. So kann zum Beispiel auch ein Filter aus einem GRResponse erstellt werden indem als stationID die Zielhaltestelle angegeben wird. Das Ergebnis würde dann nur Fahrten beinhalten, die auch tatsächlich über diese Zielhaltestelle fahren, während solche Fahrten nicht geliefert werden würden, die zwar in die richtige Richtung fahren, aber bereits vor der angegebenen Haltestelle enden (Wird als Richtung für die U2 beispielsweise Niendorf Nord angegeben, werden keine Fahrten zurückgegeben die bereits in Niendorf Markt enden). Bei Ringlinien werden nur die Fahrten übermittelt die den kürzeren Weg im Ring zur angegebenen Haltestelle haben (Bei der U3 von Barmbek in Richtung Berliner Tor beispielsweise würden nur Fahrten der U3 im Uhrzeigersinn geliefert werden).
Des Weiteren gibt es über das Feld serviceTypes die Möglichkeit nach Verkehrsmitteln zu filtern. Die Typen aus der Enumeration FilterServiceType sind in Tabelle Tabelle 29 beschrieben.
| ZUG |
Alle Züge inkl. U-Bahnen, S-Bahnen, AKNs, R-Bahnen und Fernbahnen |
| UBAHN |
Die U-Bahn-Linien der Hamburger Hochbahn AG |
| SBAHN |
Die S-Bahn-Linien der S-Bahn Hamburg |
| AKN |
Die Linien der AKN Eisenbahn AG |
| RBAHN |
Regional-Express und Regionalbahn |
| FERNBAHN |
Fernverkehrszüge wie z.B. Intercity-Express |
| BUS |
Alle Busse inkl. Stadtbusse, Metrobusse, Schnellbusse, Nachtbusse, XpressBusse und Anruf-Sammel-Taxis |
| STADTBUS |
Stadt- und Regionalbusse |
| METROBUS |
Metrobusse |
| SCHNELLBUS |
Schnellbusse |
| NACHTBUS |
Nachtbusse |
| XPRESSBUS |
XpressBusse |
| AST |
Anruf-Sammel-Taxis |
| FAEHRE |
Fähren wie z.B. die Hafenfähren der HADAG Seetouristik und Fährdienst AG |
Zu beachten ist, dass die Typen UBAHN, SBAHN, AKN, RBAHN und FERNBAHN vollständig in ZUG und die Typen STADTBUS, METROBUS, SCHNELLBUS, NACHTBUS, XPRESSBUS und AST vollständig in BUS enthalten sind. Es ist somit nicht sinnvoll Typen wie beispielsweise METROBUS und BUS gemeinsam zu verwenden.
Wird im DLRequest das Feld returnFilters auf true gesetzt, wird im DLResponse in den Feldern serviceTypes und filter sinnvolle Filtermöglichkeiten für diese Anfrage zurückgegeben. Diese Filtermöglichkeiten können dem Benutzer direkt zur Filterauswahl angeboten werden.
In diesem Beispiel werden die nächsten (höchstens 10) Abfahrten (in den nächsten, max. 200 Minuten) von der Station Rosenhof zu einem gegebenen Zeitpunkt angefragt.
Es werden drei Fahrten gefunden (von denen eine hier ausführlich zitiert wird) und mit ausführlichen stationsbezogenen Details zurückgegeben. Das Feld timeOffset ist anfragebezogen und gibt die Differenz zwischen time der Anfrage und Abfahrt in Minuten an.
1{ 2 "version": 61, 3 "station": { 4 "name": "Rosenhof", 5 "city": "Ahrensburg", 6 "combinedName": "Ahrensburg, Rosenhof", 7 "id": "Master:35009", 8 "type": "STATION", 9 "coordinate": {...} 10 }, 11 "time": { 12 "date": "11.10.2017", "time": "21:28" 13 }, 14 "maxList": 10, 15 "maxTimeOffset": 200, 16 "useRealtime":true 17}
1{ 2 "returnCode": "OK", 3 "time": { 4 "date": "11.10.2017", 5 "time": "21:28" 6 }, 7 "departures": [ 8 { 9 "line": { 10 "name": "476", 11 "direction": "Ahrensburg, Auestieg", 12 "origin": "Bf. Ahrensburg", 13 "type": { 14 "simpleType": "BUS", 15 "shortInfo": "Bus", 16 "longInfo": "Niederflur Stadtbus", 17 "model": "Niederflur Stadtbus" 18 }, 19 "id": "VHH:476_VHH" 20 }, 21 "timeOffset": 20, 22 "serviceId": 200023670, 23 "station": { 24 "combinedName": "Ahrensburg, Rosenhof", 25 "id": "Master:35009" 26 } 27 }, 28 { 29 "line": { 30 "name": "8110", 31 "direction": "Bf. Bad Oldesloe (ZOB)", 32 "origin": "Bf. Ahrensburg", 33 "type": { 34 "simpleType": "BUS", 35 "shortInfo": "Bus", 36 "longInfo": "Stadtbus", 37 "model": "Stadtbus" 38 }, 39 "id": "AKma:8110_AKma_AKMA" 40 }, 41 "timeOffset": 26, 42 "serviceId": 200059035, 43 "station": { 44 "combinedName": "Ahrensburg, Rosenhof", 45 "id": "Master:35009" 46 } 47 }, 48 ... 49 ] 50}
Im zweiten Beispiel werden Abfahrten von mehreren Haltestellen gesucht.
1{ 2 "version": 61, 3 "stations": [ 4 { 5 "name": "Groß Flottbeker Straße", 6 "city": "Hamburg", 7 "combinedName": "Groß Flottbeker Straße", 8 "id": "Master:80086", 9 "type": "STATION", 10 "coordinate": { ... } 11 }, 12 { 13 "name": "Flottbeker Drift", 14 "city": "Hamburg", 15 "combinedName": "Flottbeker Drift", 16 "id": "Master:80097", 17 "type": "STATION", 18 "coordinate": { ... } 19 } 20 ], 21 "time": { 22 "date": "heute", "time": "jetzt" 23 }, 24 "maxList": 10, 25 "maxTimeOffset": 200 26}
Der TariffRequest liefert zu einer Fahrt eine Liste von gültigen Fahrkarten.
URL: /gti/public/getTariff
Für die Berechnung werden natürlich Start, Ziel, Zeitpunkt und eine eindeutige Beschreibung des
gewählten Weges benötigt. Letztere wird über die kostenpflichtigen scheduleElements sichergestellt.
Umsteigefußwege sind zwar kostenlos, aber nicht zu übertragen. Der Request wird in Tabelle 30
beschrieben.
| Feld | Typ |
Beschreibung |
| scheduleElements | Liste von ScheduleElementLight |
Liste der Streckenabschnitte. Da ScheduleElement mit SDNames in from/to sowie einem Path sehr groß ist, gibt es hier die Light-Version ScheduleElementLight. |
| departure | GTITime |
Abfahrtszeitpunkt des ersten ScheduleElements |
| arrival | GTITime |
Ankunftszeitpunkt des letzten ScheduleElements. Optional, wenn nicht gesetzt, wird keine 9-Uhr-Tageskarte beauskunftet. |
| returnReduced | boolean |
Entscheidet, ob zusätzlich Preise ermäßigter elektronischer Tickets zurückgegeben werden. Optional, default ist false |
| tariffInfoSelector | Liste von TariffInfoSelector |
Dient zur Filterung von Tarifgruppen und Tarifkinds. Seit API Version 54 |
Die TariffResponse besteht ausschließlich aus einer Liste von TariffInfo-Objekten. Diese enthalten einerseits Informationen über die verwendeten Tarifzonen der gegeben Route (tariffRegions) und andererseits die für diese Tarifzonenkombinationen gültigen Tickets (ticketInfos). Der Typ TariffInfo wird in Tabelle 32 beschrieben.
| Feld |
Typ |
Beschreibung |
| tariffName |
String |
Die Region des Tarifs (z.B. HVV, HL, SH) |
| extraFareType |
Enum |
NO: Es wird kein Zuschlag benötigt |
| tariffRegions |
Liste von |
Die TariffRegionInfo enthalten je ein Enum TariffRegionType (Enums ZONE, GH_ZONE, RING, COUNTY) sowie eine Liste von TariffRegionList, die eine Liste ihres einzigen Feldes regions (String) speichert. Anschaulich speichert TariffRegionInfo den Tarifbereich und die durchfahrenen Tarifzonen (Zonen, Ringe, Kreise). Weil einige Haltestellen zu zwei Tarifzonen gehören (zwischen zwei Tarifzonen liegen), sind die durchfahrenen Tarifzonen einer Fahrt mehrdeutig – alle möglichen Interpretationen werden daher als Liste von Listen gespeichert. |
| ticketInfos |
Liste von TicketInfo |
Liste der für diese Fahrt gültigen Tickets (incl. deren Gültigkeitsbereichen und Preisen), s. GetRouteResponse |
| regionTexts |
Liste von String |
Liste der durchfahrenden Tarif-Regionen |
In diesem Beispiel werden die für eine Fahrt (mit Haltestelle und Zeit von Start und Ziel) gültigen Fahrscheine angefragt. In der Response werden zunächst Eigenschaften der angefragten Fahrt wie die durchfahrenen Zonen mitgeteilt. Danach folgt eine Auflistung der gültigen Tickets samt deren Eigenschaften, der Länge wegen wurden einige herausgekürzt.
1{ 2 "language": "de", 3 "version": 61, 4 "scheduleElements": [ 5 { 6 "departureStationId": "Master:10950", 7 "arrivalStationId": "Master:37979", 8 "lineId": "DB-EFZ:RE8_DB-EFZ_Z" 9 } 10 ], 11 "departure": { 12 "date": "11.10.2017", "time": "8:04" 13 }, 14 "arrival": { 15 "date": "11.10.2017", "time": "8:29" 16 } 17}
1{ 2 "returnCode": "OK", 3 "tariffInfos": [ 4 { 5 "tariffName": "HVV", 6 "tariffRegions": [ 7 { 8 "regionType": "ZONE", 9 "alternatives": [ 10 { 11 "regions": [ 12 "000", 13 "105", 14 "205", 15 "305", 16 "405", 17 "505", 18 "605", 19 "705" 20 ] 21 } 22 ] 23 }, 24 { 25 "regionType": "RING", 26 "alternatives": [ 27 { 28 "regions": [ 29 "A", 30 "B", 31 "C", 32 "D" 33 ] 34 } 35 ] 36 }, 37 ... 38 ], 39 "extraFareType": "POSSIBLE", 40 "ticketInfos": [ 41 { 42 "tariffKindID": 1, 43 "tariffKindLabel": "Einzelkarte", 44 "tariffLevelID": 304, 45 "tariffLevelLabel": "4 Ringe", 46 "tariffGroupID": 1, 47 "tariffGroupLabel": "Einzelkarten", 48 "basePrice": 7.1, 49 "extraFarePrice": 2, 50 "regionType": "RING" 51 }, 52 { 53 "tariffKindID": 2, 54 "tariffKindLabel": "Einzelkarte Kind", 55 "tariffLevelID": 600, 56 "tariffLevelLabel": "Gesamtbereich ABCDE", 57 "tariffGroupID": 1, 58 "tariffGroupLabel": "Einzelkarten", 59 "basePrice": 2.4, 60 "extraFarePrice": 2 61 }, 62 ... 63 ] 64 } 65 ] 66}
URL: /gti/public/departureCourse
Die Methode departureCourse ruft zu einer Linie (mit Richtung) und Haltestelle alle nachfolgenden
oder vorhergehenden Haltestellen incl. Abfahrtszeiten bis zur End- bzw. Anfangshaltestelle ab. Der
DCRequest wird in Tabelle 33 beschrieben.
Eine Fahrt wird entweder durch time und direction oder durch serviceId identifiziert. Nicht ganz korrekt ist daher die Angabe in der WADL, dass alle drei Felder jeweils für sich optional wären.
| Feld | Typ |
Beschreibung |
| lineKey | string |
Der volle Line Key der Linie, für die die Haltestellen-Liste erscheinen soll (z.B. HHA U:U1_HHA-U), siehe dazu Abschnitt 1.6 |
| station | SDName |
Die Haltestelle, für die Abfahrten gesucht werden sollen. Diese muss vom Typ (SDType) Station sein |
| time | dateTime |
Abfahrtszeit der Fahrt an der angegebenen Haltestelle (nur relevant, falls keine serviceId angegeben werden kann) |
| direction | string |
Name der Ziel-Haltestelle (nur relevant, falls keine serviceId angegeben werden kann) |
| serviceId | integer |
ID der Fahrt, falls bekannt (überschreibt die Wirkung von time und direction) |
| segments | Enum SegmentSelector |
Ein SegmentSelector enthält ausschließlich einen String, der entscheidet, ob das Ergebnis die Haltestellen nach oder vor der gegebenen Haltestelle oder alle Haltestellen liefert, die zugehörigen Elemente sind BEFORE, AFTER und ALL (default) |
| showPath | boolean |
Entscheidet, ob zusätzlich ein geographischer Verlauf der Fahrt mit ausgegeben wird |
| coordinateType | CoordinateType |
Bezugssystem der Koordinaten in showPath, EPSG_4326 (default) oder EPSG_31467 |
Die DCResponse enthält eine Liste courseElements von CourseElements. Der Typ CourseElement wird in Tabelle 34 beschrieben.
| Feld | Typ |
Beschreibung |
| fromStation | SDName |
Start-Haltestelle für diesen Abschnitt |
| fromPlatform | string |
Gleis-Angabe für fromStation (falls vorhanden) |
| toStation | SDName |
Ziel-Haltestelle für diesen Abschnitt |
| toPlatform | string |
Gleis-Angabe für toStation (falls vorhanden) |
| depTime | dateTime |
Abfahrtszeit ab fromStation |
| arrTime | dateTime |
Ankunftszeit an toStation |
| path | Path |
Streckenverlauf (falls angefordert und verfügbar, derzeit nicht implementiert) |
| depDelay | int |
Abfahrts-Verspätungszeit in Sekunden (seit API Version 19) |
| arrDelay | int |
Ankunfts-Verspätungszeit in Sekunden (seit API Version 19) |
| fromExtra | boolean |
Dieses Flag wird gesetzt wenn die fromStation ein außerplanmäßig zusätzlicher Halt ist. (seit API Version 19) |
| fromCancelled | boolean |
Dieses Flag wird gesetzt wenn die angegebene Fahrt aufgrund aktueller Fahrplanabweichungen nicht an der fromStation hält. (seit API Version 19) |
| fromRealtimePlatform | string |
Das Gleis, dass als Echtzeitinformation zur fromStation übermittelt wurde. (seit API Version 21) |
| toExtra | boolean |
Dieses Flag wird gesetzt wenn die toStation ein außerplanmäßig zusätzlicher Halt ist. (seit API Version 19) |
| toCancelled | boolean |
Dieses Flag wird gesetzt wenn die angegebene Fahrt aufgrund aktueller Fahrplanabweichungen nicht an der toStation hält. (seit API Version 19) |
| toRealtimePlatform | string |
Das Gleis, dass als Echtzeitinformation zur toStation übermittelt wurde. (seit API Version 21) |
| attributes | Attribute |
Zusätzliche textuelle Informationen zu diesem Fahrtabschnitt (seit API Version 23) |
| model | String |
Zusätzliche Informationen zum Verkehrsmittel(z.B. „DT4”, „Midibus”, …) (seit API Version 24) |
Hier wird zu gegebenem Datum und Uhrzeit von der Haltestelle Rosenhof ausgehend nach den nächsten Haltestellen der Buslinie 569 bis zum Ahrensburger Bahnhof gefragt, die mit allen Details zurückgegeben werden.
1{ 2 "language": "de", 3 "version": 61, 4 "lineKey": "VHH:569_VHH", 5 "station": { 6 "name": "Rosenhof", 7 "city": "Ahrensburg", 8 "combinedName": "Ahrensburg, Rosenhof", 9 "id": "Master:35009", 10 "type": "STATION", 11 "coordinate": {"x": 10.240928, "y": 53.683071} 12 }, 13 "time": "2017-10-11T16:19:00.000+0200", 14 "direction": "Ahrensburg, Schulzentrum Am Heimgarten" 15}
1{ 2 "returnCode": "OK", 3 "courseElements": [ 4 { 5 "fromStation": { 6 "name": "Rosenhof", 7 "city": "Ahrensburg", 8 "combinedName": "Ahrensburg, Rosenhof", 9 "id": "Master:35009", 10 "type": "STATION", 11 "coordinate": { 12 "x": 10.240837, 13 "y": 53.683063 14 }, 15 "serviceTypes": [ 16 "bus" 17 ], 18 "hasStationInformation": false 19 }, 20 "toStation": { 21 "name": "Pellwormstieg", 22 "city": "Ahrensburg", 23 "combinedName": "Ahrensburg, Pellwormstieg", 24 "id": "Master:35244", 25 "type": "STATION", 26 "coordinate": { 27 "x": 10.24222, 28 "y": 53.685322 29 }, 30 "serviceTypes": [ 31 "bus" 32 ], 33 "hasStationInformation": false 34 }, 35 "model": "Niederflur Stadtbus", 36 "depTime": "2017-10-11T16:19:00.000+0200", 37 "arrTime": "2017-10-11T16:20:00.000+0200" 38 }, 39 { 40 "fromStation": { 41 "name": "Pellwormstieg", 42 "city": "Ahrensburg", 43 "combinedName": "Ahrensburg, Pellwormstieg", 44 "id": "Master:35244", 45 "type": "STATION", 46 "coordinate": { 47 "x": 10.24222, 48 "y": 53.685322 49 }, 50 "serviceTypes": [ 51 "bus" 52 ], 53 "hasStationInformation": false 54 }, 55 "toStation": { 56 "name": "Helgolandring", 57 "city": "Ahrensburg", 58 "combinedName": "Ahrensburg, Helgolandring", 59 "id": "Master:35047", 60 "type": "STATION", 61 "coordinate": { 62 "x": 10.242032, 63 "y": 53.68562 64 }, 65 "serviceTypes": [ 66 "bus" 67 ], 68 "hasStationInformation": false 69 }, 70 "model": "Niederflur Stadtbus", 71 "depTime": "2017-10-11T16:21:00.000+0200", 72 "arrTime": "2017-10-11T16:22:00.000+0200" 73 }, 74 ... 75 ] 76}
Viele Methoden nehmen SDNames als Argument. Von dessen vielen Feldern verwenden sie jedoch oft nur die Felder id, name, city und type. Weil nun Haltestellen (das sind jede SDNames mit type==STATION) besonders häufig als SDName verwendet werden, enthält eine auf id, name und city beschränkte Haltestellenliste bereits alle vier relevanten Felder eines SDName, um z.B. für ein getRoute zwei vorhergehende checkName-Aufrufe für start und dest zu sparen – was insbesondere auf mobilen Clients viel Zeit spart. Ebenfalls möglich ist mit solch einem Cache ein Vorschlager, der bereits bei wenigen eingegebenen Buchstaben Haltestellenvorschläge machen kann. Es ist vorgesehen, dass der Cache auf dem Client die Felder id, name, city und, optional für die grafische Darstellung, die Koordinaten der Stationen zwischenspeichert.
Eine solche Liste auf Endgeräten erfordert die Initialbefüllung und eine Möglichkeit zum Update. Für diese Funktionen ist listStations vorgesehen.
URL: /gti/public/listStations
Für eine Initialbefüllung des Clients ist das Feld dataReleaseID leer zu lassen. Ist es das nicht,
werden nur (vollständige) Datensätze zurückgegeben, die sich seit der angegebenen Version
hinsichtlich der drei Felder id, name, city bzw. dem Feld coordinate geändert haben (diff). Über
den Listeneintrag MAIN in der Liste modificationTypes werden Datensätze mit Änderungen in id,
name, city angewählt, über POSITION solche mit Änderungen im Feld coordinate. Ist die Liste leer,
werden Änderungen gemäß allen möglichen Werten des Enums ModificationType zurückgegeben.
Der Request wird in Tabelle 35 beschrieben.
| Feld |
Typ |
Beschreibung |
| dataReleaseID |
string |
Die bereits vorhandene Datenversion. Ein leeres Feld fragt alle Datensätze an |
| modificationTypes |
Liste von Enums ModificationType |
Legt die Felder fest, hinsichtlich welcher ein SDName als verändert betrachtet wird, derzeit sind die möglichen Felder die genannten MAIN und POSITION |
| coordinateType |
CoordinateType |
Bezugssystem der Koordinaten, EPSG_4326 (default) oder EPSG_31467 |
| filterEquivalent |
boolean |
Fügt äquivalente Haltestellen zusammen (z.B. Rödingsmarkt und U Rödingsmarkt) |
Die Response wird in Tabelle 36 beschrieben. Der Typ StationListEntry wird in Tabelle 37 beschrieben.
| Feld |
Typ |
Beschreibung |
| id |
string |
ID (wie in SDName) |
| name |
string |
Name (wie in SDName) |
| city |
string |
Ort (wie in SDName) |
| combinedName |
string |
Voller Name (wie in SDName) |
| shortcuts |
Liste aus string |
Kürzel des Haltestellennamens |
| aliasses |
Liste aus string |
Alternativbezeichnungen des Haltestellennamens |
| vehicleTypes |
Liste aus Enum VehicleType |
Die hier verkehrenden Verkehrsmittel (z.B. U_BAHN, SCHNELLBUS, SCHIFF, NACHTBUS, XPRESSBUS, AST). Entspricht dem serviceTypes aus SDName, ist aber nicht so fein aufgelöst. |
| coordinate |
Coordinate |
Koordinaten (wie in SDName) |
| exists |
Boolean |
Flag zur Übermittlung von gelöschten Haltestellen |
Wird eine Haltestelle gelöscht, werden von ihr nur die Felder id und exists (mit Wert false) zurückgegeben – damit kann der Client den Eintrag aus seinem Cache entfernen.
1{ 2 "language": "de", 3 "version":61, 4 "dataReleaseID": "29.73.01", 5 "modificationTypes": ["MAIN"] 6}
1{ 2 "returnCode": "OK", 3 "dataReleaseID": "29.74.01", 4 "stations": [ 5 { 6 "id": "Master:52982", 7 "name": "Neumühlen/Övelgönne", 8 "city": "Hamburg", 9 "combinedName": "Neumühlen/Övelgönne", 10 "shortcuts": [ 11 "neua" 12 ], 13 "aliasses": [ 14 "Neumühlen" 15 ], 16 "vehicleTypes": [ 17 "SCHIFF" 18 ] 19 }, 20 { 21 "id": "Master:19072", 22 "exists": false 23 }, 24 { 25 "id": "Master:56103", 26 "name": "Im Ort", 27 "city": "Wendhausen", 28 "aliasses": [ 29 "Reinstorf, Wendhausen", 30 "Wendhausen, Ort" 31 ], 32 "vehicleTypes": [ 33 "REGIONALBUS", 34 "AST" 35 ] 36 } 37 ] 38}
Die Methode ermöglicht es dem Client, eine Liste der bestehenden Linien als Cache vorzuhalten, ähnlich wie listStations es mit den Haltestellen ermöglicht. Dies ermöglicht einen Vorschlager für Linien.
Zunächst sind Begrifflichkeiten anzumerken: Eine Linie hat eine oder mehrere Sublinien. Sublinien sind dann gegeben, wenn beispielsweise auf einer Buslinie nur jeder zweite Bus zur Endhaltestelle fährt – die anderen Busse haben eine frühere Endhaltestelle.
Sublinien gibt es auch bei der U1, die durch das hamburger Zentrum fährt und sich draußen in Volksdorf aufteilt: Ungefähr jeder zweite Zug fährt danach Richtung Ohlstedt, die verbleibenden fahren nach Volksdorf Richtung Großhansdorf. An letzterem Beispiel ist nachvollziehbar, dass jede Sublinie eine (sortierte) Liste von Haltestellen hat. Der hier behandelten Liste einer Linie, die alle Haltestellen ihrer Sublinien speichert, kann keine Haltestellenabfolge entnommen werden.
URL: /gti/public/listLines
Der Request wird in Tabelle 38 beschrieben.
| Feld |
Typ |
Beschreibung |
| dataReleaseID |
string |
Die bereits vorhandene Datenversion. Ein leeres Feld fragt alle Datensätze an |
| modificationTypes |
Liste von Enums LineModificationType |
Legt über die Enums MAIN und SEQUENCE die Felder fest, hinsichtlich welcher eine Linie als verändert betrachtet wird |
| withSublines |
boolean |
Entscheidet, ob auch Sublinien zurückgegeben werden sollen |
Im Enum LineModificationType gibt es derzeit die Enums Main und SEQUENCE, von denen ersteres Änderungen der Linie bezüglich ihres Namens, Betreibers (Carrier, CarrierLong, CarrierShort) anfragt, während das Enum SEQUENCE Änderungen in der Haltestellenliste der Linie anfragt.
Die Response wird in Tabelle 39 beschrieben.
Der Typ LineListEntry wird in Tabelle 40 beschrieben.
Wird eine Linie gelöscht, werden von ihr nur die Felder id und exists (mit Wert false) zurückgegeben – damit kann der Client den Eintrag aus seinem Cache entfernen.
| Feld |
Typ |
Beschreibung |
| id |
string |
ID der Linie |
| name |
string |
Name der Linie, z.B. U1 |
| carrierNameShort |
string |
Namenskürzel des Betreibers |
| carrierNameLong |
string |
Name des Betreibers |
| sublines |
Liste von SublineListEntry |
Die Liste der Sublinien dieser Linie |
| exists |
boolean |
Flag zur Übermittlung von gelöschten Haltestellen |
| type |
ServiceType |
Beschreibt den Fahrzeugtyp der Linie. Es werden nur die Felder simpleType und shortInfo gefüllt. |
Der Typ SublineListEntry wird in Tabelle 41 beschrieben.
| Feld |
Typ |
Beschreibung |
| sublineNumber |
string |
Interne Nummer der Sublinie. Diese kann sich häufig ändern, z.B. bei neuer Datenversion. |
| vehicleType |
VehicleType |
Das Verkehrsmittel der Sublinie (z.B. U_BAHN, SCHNELLBUS, SCHIFF, NACHTBUS, XPRESSBUS, AST). Entspricht dem serviceTypes aus SDName, ist aber nicht so fein aufgelöst. |
| stationSequence |
Liste von StationLight |
Diese Liste enthält die Stationen dieser Sublinie |
Der Typ StationLight wird in Tabelle 42 beschrieben.
1{ 2 "language": "de", 3 "version": 61, 4 "dataReleaseID": "29.71.01", 5 "modificationTypes": ["MAIN"] 6}
1{ 2 "returnCode": "OK", 3 "dataReleaseID": "29.74.01", 4 "lines": [ 5 { 6 "id": "HHA-B:175_HHA-B", 7 "exists": false 8 }, 9 { 10 "id": "KVGBer:Elb-Shuttle_KVGBer_KVGM", 11 "exists": false 12 }, 13 { 14 "id": "HHA-B:U3-SEV_HHA-B", 15 "exists": false 16 }, 17 { 18 "id": "KVGBer:Elbe-Radwanderbus_KVGBer_KVGM", 19 "exists": false 20 }, 21 { 22 "id": "KVGBer:Regionalpark-Shuttle_KVGBer_KVGM", 23 "exists": false 24 }, 25 { 26 "id": "HHA-B:SEV-U3_HHA-B", 27 "name": "SEV-U3", 28 "carrierNameShort": "Hochbahn", 29 "carrierNameLong": "Hamburger Hochbahn AG", 30 "exists": true 31 } 32 ] 33}
URL: /gti/public/getAnnouncements
Der AnnouncementRequest fragt die aktuellen Fahrplanabweichungen ab. Die Menge der
zurückgegebenen Meldungen kann dabei z.B. nach Zeitraum, Linie oder Verkehrsunternehmen
gefiltert werden. Der Request wird in Tabelle 43 beschrieben.
| Feld |
Typ |
Beschreibung |
| names |
Liste von String |
Liste von zu betrachtenden Liniennamen oder Verkehrsunternehmen, z.B. „S1”, „2” oder „KVG”. |
| timeRange |
TimeRange |
Besteht aus den beiden dateTime-Objekten begin und end (siehe Abschnitt 1.6). Nur Meldungen dieses Zeitintervalls ausgeben. Optional (falls nicht gesetzt, werden alle aktuellen Meldungen zurückgegeben) |
| full |
boolean |
Gibt an ob die Antwort vollständige Linien, Haltestellen und Gültigkeitsinformationen enthalten soll. |
| filterPlanned |
AnnouncementFilter- PlannedType |
Filterung der Announcements nach dem Flag planned. (optional, seit API Version 30) |
| showBroadcastRelevant |
boolean |
Filterung der Announcements nach dem Flag broadcastRelevant. (optional, seit API Version 46) |
Der Enum AnnouncementFilterPlannedType kann folgende Werte annehmen: ONLY_PLANNED, ONLY_UNPLANNED und NO_FILTER. Anhand dieser Werte werden die Announcements nach dem Flag planned gefiltert, oder auch nicht. Ist das Feld filter z.B. nicht gesetzt, so wird wie auch im Fall von NO_FILTER nicht gefiltert.
Die AnnouncementResponse enthält den Zeitpunkt der letzten Aktualisierung und eine Liste der einzelnen Meldungen. Sie wird in Tabelle 44 beschrieben.
Der Typ Announcement wird in Tabelle 45 beschrieben.
| Feld | Typ |
Beschreibung |
| id | string |
Eindeutige ID für diese Meldung |
| version | integer |
Versionsnummer für diese Meldung |
| locations | Liste von Location |
Die Location beschreibt die Region bzw. die Fahrten die von dem beschriebenen Ereignis betroffen sind. Falls eine veraltete bzw. nicht mehr vorhandene Haltestelle betroffen ist, kann diese Liste auch leer sein. (siehe Tabelle 46). |
| summary | string |
Der Kurzmeldungstext, ein zusammenfassender Satz, der z.B. als Überschrifft verwendet werden kann. Wird im Fall von ungeplanten Meldungen nicht gesetzt. |
| description | string |
Der ausführliche Meldungstext |
| links | Liste von Link |
Eine Liste von Links mit zusätzlichen Informationen zur Meldung (z.B. Ersatzfahrplan als PDF o.ä.). Ein Link enthält die beiden Strings label und url. |
| publication | TimeRange |
Veröffentlichungszeitraum, also der Zeitraum in dem die Meldung für den Fahrgast angezeigt werden soll. |
| validities | Liste von TimeRange |
Liste der Gültigkeitszeiträume, also die Zeiträume in denen Fahrten vom beschriebenen Ereignis betroffen sind. |
| lastModified | DateTime |
Zeitpunkt der letzten Aktualisierung dieser Meldung (Entspricht immer dem Erstellungszeitpunkt, da Meldungen grundsätzlich nicht verändert sondern nur durch neue Meldungen ersetzt werden können). |
| planned | boolean |
Entspricht das Announcement einem geplanten Ereignis? (seit API Version 30) |
| reason | String |
Der Grund für das Ereignis. Ein kurzer Schlüssel, der nur feste Werte annehmen kann. Mögliche Werte werden in Tabelle 47 aufgezählt. (seit API Version 30) |
| broadcastRelevant | boolean |
Ist das Announcement relevant für die Veröffentlichung im öffentlichen Rundfunk? (seit API Version 46) |
Die Location beschreibt die Region bzw. die Fahrten die von dem beschriebenen Ereignis betroffen sind. Dies können einzelne Linien aber auch ganze Netze oder Verkehrsunternehmen sein. Die Location wird nur dann mit detaillierten Informationen gefüllt, wenn das Feld full auf true gesetzt ist. Die Location wird in Tabelle 46 beschrieben.
Falls das Startdatum des ScheduleElement innerhalb des publication-Zeitraums des Announcements, aber nicht innerhalb eines validities-Zeitraums des Announcements liegt, so handelt es sich um eine Vorankündigung.
| Feld | Typ |
Beschreibung |
| type | LocationType |
Beschreibungstyp, möglich sind einzelne Linien, alle Linien eines Betreibers oder ein gesamtes Netz. |
| name | string |
Wenn ein ganzer Betreiber oder ein ganzes Netz betroffen ist, steht hier um welches es sich handelt. |
| line | Service |
Wenn eine einzelne Linie betroffen ist, steht hier um welche es sich handelt (siehe Tabelle 53). |
| begin | SDName |
Die erste Haltestelle auf der angegebenen Linie, die betroffen ist (null = Die ganze Linie ist betroffen). |
| end | SDName |
Die letzte Haltestelle auf der angegebenen Linie, die betroffen ist (null = Die ganze Linie ist betroffen). |
| bothDirections | boolean |
Wenn eine einzelne Linie betroffen ist, ist hier angegeben ob nur die angegebene, oder beide Richtungen, betroffen sind. Der Richtungstext der Gegenrichtung kann dann dem Feld Origin im Service entnommen werden. |
Das Feld reason nimmt im Moment nur folgende mögliche Werte an:
In diesem Beispiel werden alle Meldungen zur Linie S3 angefragt. Es wird eine Meldung zurückgegeben, die die Linie S3 in beide Richtungen betrifft. Zusätzlich werden mehrere Links mit weiteren Informationen für den Fahrgast angegeben.
1{ 2 "language": "de", 3 "version": 61, 4 "names": [ 5 "S3" 6 ], 7 "full": true 8}
1{ 2 "returnCode": "OK", 3 "announcements": [ 4 { 5 "id": "171012003C", 6 "locations": [ 7 { 8 "type": "SINGLE_LINE", 9 "line": { 10 "name": "S1", 11 "direction": "Poppenbüttel / Hamburg Airport (Flughafen)", 12 "origin": "Wedel", 13 "type": { 14 "simpleType": "TRAIN", 15 "shortInfo": "S", 16 "longInfo": "S-Bahn" 17 }, 18 "id": "ZVU-DB:S1_ZVU-DB_S-ZVU", 19 "dlid": "de:hvv:S1:" 20 }, 21 "begin": { 22 "name": "Poppenbüttel", 23 "city": "Hamburg", 24 "combinedName": "Poppenbüttel", 25 "id": "Master:71953", 26 "type": "STATION" 27 }, 28 "end": { 29 "name": "Wedel", 30 "city": "Wedel", 31 "combinedName": "Wedel", 32 "id": "Master:85950", 33 "type": "STATION" 34 } 35 }, 36 { 37 "type": "SINGLE_LINE", 38 "line": { 39 "name": "S11", 40 "direction": "Poppenbüttel", 41 "origin": "Blankenese", 42 "type": { 43 "simpleType": "TRAIN", 44 "shortInfo": "S", 45 "longInfo": "S-Bahn" 46 }, 47 "id": "ZVU-DB:S11_ZVU-DB_S-ZVU", 48 "dlid": "de:hvv:S1:" 49 }, 50 "begin": { 51 "name": "Poppenbüttel", 52 "city": "Hamburg", 53 "combinedName": "Poppenbüttel", 54 "id": "Master:71953", 55 "type": "STATION" 56 }, 57 "end": { 58 "name": "Blankenese", 59 "city": "Hamburg", 60 "combinedName": "Blankenese", 61 "id": "Master:81950", 62 "type": "STATION" 63 } 64 }, 65 ... 66 ], 67 "description": " \nAufgrund eines mittlerweile behobenen Stromausfalls am Hamburger Hauptbahnhof kommt es noch auf allen Linien zu Zugausfällen und Verspätungen. Die Züge der Linie S11 fallen aus.", 68 "publication": { 69 "begin": "2015-01-01T13:00:00.000+0100", 70 "end": "2017-10-12T10:00:00.000+0200" 71 }, 72 "validities": [ 73 { 74 "begin": "2017-10-12T08:00:00.000+0200", 75 "end": "2017-10-12T10:00:00.000+0200" 76 } 77 ], 78 "lastModified": "2017-10-12T08:34:55.877+0200" 79 }, 80 ... 81 ], 82 "lastUpdate": "2017-10-12T08:34:55.877+0200" 83}
Diese Methode berechnet Routen im Individualverkehr. Derzeit versteht das GTI darunter Fußwege und Radstrecken.
Im Request können mehrere Startpunkte und mehrere Ziele angeben werden. Bei mehreren Zielen wird stets zu jedem Ziel eine Route zurückgegeben. Sind gleichzeitig mehrere Starts gegeben, starten die zurückgegeben Routen beim dichtesten Start aus der Menge der Startpunkte, es gibt also nicht zwingend zu jedem Start eine Route. Über die Felder maxLength und maxResults des Requests können Routen verworfen werden. Der erste Parameter veranlasst ein Verwerfen von zu langen Routen, der zweite wählt eine Anzahl an kürzesten Routen.
Soll also beispielsweise der Fußweg zur dichtesten Haltestelle berechnet werden, kann über ein checkName vom Typ STATION eine Liste der Haltestellen im Umfeld angefragt werden, die zusammen mit maxResults=1 an getIndividualRoute gegeben wird. Die IndividualRouteResponse enthält dann die Route der gegebenen Position zur nächstgelegenen Haltestelle.
Optional ist die Angabe des Verkehrsmitteltyps (serviceType) oder eines Individualprofils (profile). Der Router berücksichtigt über das Profil bestimmte Einschränkungen oder Neigungen des Verkehrsteilnehmers. Beispielsweise werden Rennradfahrer bevorzugt über befestigte Strecken geleitet.
URL: /gti/public/getIndividualRoute
Der IndividualRouteRequest wird in Tabelle 48 beschrieben.
| Feld |
Typ |
Name |
| starts |
Liste von SDName |
Liste der Startpunkte (muss gefüllt sein) |
| dests |
Liste von SDName |
Liste der Zielpunkte (muss gefüllt sein) |
| maxLength |
Integer |
Maximale Länge der Ergebnisrouten in Metern |
| maxResults |
Integer |
Maximale Anzahl von Ergebnisrouten |
| type |
CoordinateType |
Bezugssystem der Koordinaten, EPSG_4326 (default) oder EPSG_31467. |
| serviceType |
SimpleServiceType |
Verkehrsmitteltyp, optional, default: FOOTPATH |
| profile |
IndividualProfileType |
Individualprofil, optional, default: FOOT_NORMAL |
Die IndividualRouteResponse besteht aus einer Liste von IndiviualRoutes die in Tabelle 50 beschrieben werden.
| Feld |
Typ |
Name |
| start |
SDName |
Start der Route |
| dest |
SDName |
Ziel der Route |
| paths |
Path |
Streckenverlauf als Liste von Pfaden mit Attributen (z. B. Oberflächenbeschaffenheit) |
| length |
Integer |
Länge der Route in Metern |
| time |
Integer |
Geschätzte Fußweg-/Fahrzeit in Sekunden |
| serviceType |
SimpleServiceType |
Verkehrsmitteltyp der berechneten Routen |
1{ 2 "version": 61, 3 "starts":[ 4 { 5 "name":"HBT - Hamburger Berater Team", 6 "city":"Hamburg", 7 "combinedName":"HBT - Hamburger Berater Team", 8 "id":"1501000", 9 "type":"POI", 10 "coordinate":{"x":9.985721, "y":53.549983} 11 } 12 ], 13 "dests":[ 14 { 15 "name":"Niendorf Nord", 16 "city":"Hamburg", 17 "combinedName":"Niendorf Nord", 18 "id":"Master:91900", 19 "type":"STATION", 20 "coordinate":{"x":9.950054, "y":53.640807} 21 } 22 ], 23 "type":"EPSG_4326", 24 "serviceType":"FOOTPATH" 25}
1{ 2 "returnCode": "OK", 3 "routes": [ 4 { 5 "start": { 6 "name": "HBT - Hamburger Berater Team", 7 "city": "Hamburg", 8 "combinedName": "HBT - Hamburger Berater Team", 9 "id": "1501000", 10 "type": "POI", 11 "coordinate": { "x": 9.985721, "y": 53.549983 } 12 }, 13 "dest": { 14 "name": "Niendorf Nord", 15 "city": "Hamburg", 16 "combinedName": "Niendorf Nord", 17 "id": "Master:91900", 18 "type": "STATION", 19 "coordinate": { "x": 9.950054, "y": 53.640807 } 20 }, 21 "paths": [ 22 { 23 "track": [ 24 { "x": 9.985726, "y": 53.54998 }, 25 { "x": 9.985862, "y": 53.549988 }, 26 { "x": 9.985835, "y": 53.550158 }, 27 { "x": 9.985822, "y": 53.550248 }, 28 { "x": 9.985782, "y": 53.550473 }, 29 { "x": 9.985843, "y": 53.550482 } 30 ], 31 "attributes": [ 32 "SURFACE_UNKNOWN" 33 ] 34 }, 35 ... 36 ], 37 "length": 12060, 38 "time": 181, 39 "serviceType": "FOOTPATH" 40 } 41 ] 42}
Die Methode getVehicleMap ermöglicht es dem Client eine Liste aller ÖV-Fahrzeuge und deren Fahrtverlauf zu einem bestimmten Zeitabschnitt in einer bestimmten Gegend zu erhalten. Dabei kann spezifiziert werden, ob Fahrplandaten oder Livedaten verwendet werden sollen.
Dabei werden für alle Fahrzeuge, die im Laufe ihrer Fahrt die Gegend (Bounding-Box) schneiden, die Streckenabschnitte zurück gegeben, die den Zeitabschnitt schneiden und wiederum den Ausschnitt schneiden.
Aus Perfomancegründen sollte das Flag VehicleMapRequest.withoutCoords gesetzt werden. In diesem Fall können über den TrackCoordinatesRequest die Koordinaten für die Streckenabschnitte bei Bedarf nachgeholt werden.
Diese Methode kann z.B. benutzt werden um eine Karte mit den aktuellen Fahrzeugpositionen anzuzeigen.
URL: /gti/public/getVehicleMap
Der Request wird in Tabelle 51 beschrieben.
| Feld |
Typ |
Name |
| boundingBox |
BoundingBox |
Der Ausschnitt (Gegend) |
| periodBegin |
Long |
Zeitstempel des Periodenbegins (UNIX-time) |
| periodEnd |
Long |
Zeitstempel des Periodenendes (UNIX-time) |
| withoutCoords |
Boolean |
Es sollen keine Koordinaten zurückgesendet werden |
| coordinateType |
CoordinateType |
Das gewünschte Koordinatenreferenzsystem, Achtung: der Server muss sich nicht daran halten |
| vehicleTypes |
Liste von VehicleType |
Die Liste der gewünschten Fahrzeugtypen |
| realtime |
boolean |
Bestimmt, ob Echtzeit- oder Fahrplandaten zurückgegeben werden sollen |
Eine BoundingBox enthällt 2 Coordinate: lowerLeft & upperRight, welche zwischen sich ein Gebiet eingrenzen (in der GIS-Sprache: Envelope oder BoundingBox)
Die Response besteht aus einer Liste von Journey(Fahrten), die in Tabelle 52 beschrieben werden.
| Feld |
Typ |
Name |
| journeyID |
String |
Eindeutige ID der Fahrt |
| line |
Service |
Eindeutige ID der Linie, deren Teil die Fahrt ist. Wird in Tabelle 53 beschrieben |
| vehicleType |
VehicleType |
Der Fahrzeugtyp, mit dem diese Linie betrieben wird. Mögliche Werte sind in Tabelle 56 aufgezählt. |
| realtime |
Boolean |
Zeigt an, ob die Daten echtzeitbehaftet sind |
| segments |
Liste von PathSegment |
Die Streckenabschnitte |
| Feld |
Typ |
Name |
| name |
String |
Der Name der Linie, z.B. ”S1” |
| direction |
String |
Ziel/Richtung der Fahrt |
| origin |
String |
Start/Ursprung der Fahrt |
| type |
ServiceType |
Typ der Linie, wird in Tab. 54 beschrieben |
| id |
String |
ID der Linie |
| dlid |
String |
DLID der Linie |
| Feld |
Typ |
Name |
| simpleType |
SimpleServiceType |
Type der Linie, Eine Auzählung, die in Tab. 55 beschrieben wird |
| shortInfo |
String |
Eine kurze Info zur Linie |
| longInfo |
String |
Eine längere Info zur Linie |
| model |
String |
Zusätzliche Informationen über die Art des Verkehrsmittels, z.B („DT4”, „Midibus”, …) (Seit API Version 24) |
| Wert |
Beschreibung |
| REGIONALBUS |
Regionalbusse. Busse, die nicht unter die vier folgenden Bustypen fallen |
| METROBUS |
Metrobus |
| NACHTBUS |
Nachtbus |
| SCHNELLBUS |
Schnellbus |
| XPRESSBUS |
XpressBus |
| AST |
Anruf-Sammel-Taxi, sonstige Verkehrsmittel, die nur bei vorherigem Telefonanruf fahren |
| SCHIFF |
Fähre |
| U_BAHN |
U-Bahn |
| S_BAHN |
S-Bahn |
| A_BAHN |
A-Bahn |
| R_BAHN |
Regionalbahn |
| F_BAHN |
Fernbahn |
Der Typ PathSegment wird in Tabelle 57 beschrieben.
| Feld |
Typ |
Name |
| startStopPointKey |
String |
Der StopPointKey des Segment-Starts |
| endStopPointKey |
String |
Der StopPointKey des Segment-Endes |
| startStationName |
String |
Der Stationsname des Segment-Starts |
| startStationKey |
String |
Der StationKey des Segment-Starts |
| startDateTime |
String |
Der Zeitstempel zu dem das Fahrzeug am Anfang des Tracks ist (UNIX-time) |
| endStationName |
String |
Der Stationsname des Segment-Endes |
| endStationKey |
String |
Der StationKey des Segment-Endes |
| endDateTime |
String |
Der Zeitstempel zu dem das Fahrzeug am Ende des Tracks ist (UNIX-time) |
| track |
VehicleMapPath |
Streckenverlauf in Koordinaten. Wird nur gesetzt, falls withoutCoords im Request nicht gesetzt ist. |
| destination |
String |
Richtung der Fahrt. Informationsgehalt hängt von diesem Streckenabschnitt ab |
| realtimeDelay |
Integer |
Verspätung in Minuten |
| isFirst |
Boolean |
Zeigt an, ob dies der erste Abschnitt der Fahrt ist |
| isLast |
Boolean |
Zeigt an, ob dies der letzte Abschnitt der Fahrt ist |
Der Typ VehicleMapPath ist eine platzsparendere Version des Typs Path. Er wird in Tabelle 58 beschrieben.
1{ 2 "version":61, 3 "boundingBox":{ 4 "lowerLeft":{"x":9.986250400543213, "y":53.54789377955267, "type":"EPSG_4326"}, 5 "upperRight":{"x":9.739487171173096, "y":53.40829355253501, "type":"EPSG_4326"} 6 }, 7 "periodBegin":1507797056, 8 "periodEnd":1507840256, 9 "withoutCoords":true, 10 "coordinateType":"EPSG_31467", 11 "vehicleTypes":["F_BAHN", "R_BAHN", "S_BAHN", "A_BAHN", "SCHIFF", "XPRESSBUS"], 12 "realtime":false 13}
1{ 2 "returnCode": "OK", 3 "journeys": [ 4 { 5 "journeyID": "ZVU-DB:S3_ZVU-DB_S-ZVU.1.52.PISTAD.N.520.null (subline 52, sdIndex 10, Fahrt 0)", 6 "line": { 7 "name": "S3", 8 "direction": "Stade", 9 "type": { 10 "simpleType": "TRAIN" 11 }, 12 "id": "ZVU-DB:S3_ZVU-DB_S-ZVU" 13 }, 14 "vehicleType": "S_BAHN", 15 "realtime": true, 16 "segments": [ 17 { 18 "startStopPointKey": "ZVU-DB:499101:1", 19 "endStopPointKey": "ZVU-DB:409101:1", 20 "startStationName": "Harburg", 21 "startStationKey": "Master:49950", 22 "startDateTime": 1507797660, 23 "endStationName": "Harburg Rathaus", 24 "endStationKey": "Master:40950", 25 "endDateTime": 1507797780, 26 "destination": "Stade", 27 "realtimeDelay": 7, 28 "isFirst": false, 29 "isLast": false 30 }, 31 { 32 "startStopPointKey": "ZVU-DB:409101:1", 33 "endStopPointKey": "ZVU-DB:429101:1", 34 "startStationName": "Harburg Rathaus", 35 "startStationKey": "Master:40950", 36 "startDateTime": 1507797780, 37 "endStationName": "Heimfeld", 38 "endStationKey": "Master:42950", 39 "endDateTime": 1507797840, 40 "destination": "Stade", 41 "realtimeDelay": 6, 42 "isFirst": false, 43 "isLast": false 44 }, 45 ... 46 ] 47 }, 48 { 49 "journeyID": "ZVU-DB:S1_ZVU-DB_S-ZVU.6.6.PBSB .N.520.null (subline 6, sdIndex 1, Fahrt 2)", 50 "line": { 51 "name": "S1", 52 "direction": "Blankenese", 53 "type": { 54 "simpleType": "TRAIN" 55 }, 56 "id": "ZVU-DB:S1_ZVU-DB_S-ZVU" 57 }, 58 "vehicleType": "S_BAHN", 59 "realtime": true, 60 "segments": [ 61 { 62 "startStopPointKey": "ZVU-DB:119107:1", 63 "endStopPointKey": "ZVU-DB:809101:1", 64 "startStationName": "Stadthausbrücke", 65 "startStationKey": "Master:11952", 66 "startDateTime": 1507799580, 67 "endStationName": "Landungsbrücken", 68 "endStationKey": "Master:80950", 69 "endDateTime": 1507799700, 70 "destination": "Blankenese", 71 "realtimeDelay": 0, 72 "isFirst": false, 73 "isLast": false 74 }, 75 { 76 "startStopPointKey": "ZVU-DB:809101:1", 77 "endStopPointKey": "ZVU-DB:809103:1", 78 "startStationName": "Landungsbrücken", 79 "startStationKey": "Master:80950", 80 "startDateTime": 1507799700, 81 "endStationName": "Reeperbahn", 82 "endStationKey": "Master:80951", 83 "endDateTime": 1507799820, 84 "destination": "Blankenese", 85 "realtimeDelay": 0, 86 "isFirst": false, 87 "isLast": false 88 }, 89 ... 90 ] 91 }, 92 ... 93 ] 94}
URL: /gti/public/getTrackCoordinates
Der Client erhält die Koordinaten zu bestimmten Streckenabschnitten durch den
TrackCoordinatesRequest. Da einige Streckenabschnitte öfters angefragt werden, ist es
ökonomischer, nur einmal die Koordinaten für diese Abschnitte anzufragen. Hierzu dient dieser
Request, der in Tabelle 59 beschrieben wird.
| Feld |
Typ |
Name |
| coordinateType |
CoordinateType |
Das gewünschte Koordinatenreferenzsystem, Achtung: der Server muss sich nicht daran halten |
| stopPointKeys |
Liste von String |
Eine Liste von StopPointKeys. Je zwei aufeinanderfolgende Strings representieren einen Streckenabschnitt. |
Die Response besteht aus zwei geordneten Listen. Das n-te Element von TrackCoordinatesResponse.trackIDs(Ein String, bestehend aus dem Start-StopPointKey des Streckenabschnitts, einem ”∗” und dem End-StopPointKey des Streckabschnitts) identifiziert das n-te Element von TrackCoordinatesResponse.tracks(Ein VehicleMapPath, der die Koordinaten für einen Streckenabschnitt enthält).
1{ 2 "version":61, 3 "coordinateType":"EPSG_4326", 4 "stopPointKeys":[ 5 "ZVU-DB:8004248:2","ZVU-DB:8004247:2", 6 "ZVU-DB:809100:1","ZVU-DB:119106:1", 7 "ZVU-DB:429101:1","ZVU-DB:419103:1", 8 ... 9 ] 10}
1{ 2 "returnCode": "OK", 3 "trackIDs": [ 4 "ZVU-DB:8004248:2*ZVU-DB:8004247:2", 5 "ZVU-DB:809100:1*ZVU-DB:119106:1", 6 "ZVU-DB:429101:1*ZVU-DB:419103:1", 7 ... 8 ], 9 "tracks": [ 10 { 11 "track": [ 12 9.819357930428565, 13 53.474756741591555, 14 9.819357757192398, 15 53.4747477574321, 16 ... 17 ], 18 "coordinateType": "EPSG_4326" 19 }, 20 { 21 "track": [ 22 9.970592739589032, 23 53.54623412569607, 24 9.971028521129297, 25 53.546158702368494, 26 ... 27 ], 28 "coordinateType": "EPSG_4326" 29 }, 30 { 31 "track": [ 32 9.963175016379674, 33 53.465407532129674, 34 9.963159757749652, 35 53.46539866976629, 36 ... 37 ], 38 "coordinateType": "EPSG_4326" 39 }, 40 ... 41 ] 42}
URL: /gti/public/checkPostalCode
Ein Aufruf von checkPostalCode liefert zu einem PCRequest eine PCResponse, die angibt, ob das
Postleitzahlgebiet im HVV Bereich liegt. Der PCRequest besitzt nur das Feld postalCode mit Typ
Integer, welches die zu prüfende Postleitzahl enthält.
Das Beispiel in den Listings 31 und 32 zeigt den möglichen PCRequest.
Die Methode getStationInformation liefert zu einer Haltestelle zusätzliche Informationen. Diese können einen Link zu einer Haltestellenskizze, oder Informationen über Aufzüge an dieser Haltestelle beinhalten. Ob diese zusätzlichen Informationen vorhanden sind, steht im Feld SDName.hasStationInformation, welches z.B. über einen checkName ermittelt wird.
URL: /gti/public/getStationInformation
Die Methode getStationInformation nimmt als Eingabe einen StationInformationRequest.
Die zu überprüfende Haltestelle wird im Feld StationInformationRequest.station als SDName
angegeben.
Die Methode getStationInformation liefert als Ergebnis eine StationInformationResponse zurück. In Tabelle 60 werden die Felder vorgestellt.
Das Feld partialStations ist meistens nur mit einem Eintrag gefüllt, welcher für die gesamte Haltestelle steht. Es gibt jedoch auch Ausnahmen, wie z.B. Berliner Tor, bei der der U-Bahn-Verkehr separat in einem zweiten Eintrag behandelt wird. Der Typ PartialStation wird in Tabelle 61 beschrieben.
| Feld | Typ |
Beschreibung |
| lines | Liste von strings |
Beinhaltet die Linien, welche an dieser Teilhaltestelle bedient werden. Kann leer oder ungesetzt sein. |
| stationOutline | URL |
Link zu einer Haltestellenskizze für diese Teilhaltestelle. |
| elevators | Liste von Elevator |
Die Aufzüge an dieser Teilhaltestelle. |
Falls das Feld lines leer oder ungesetzt ist, so werden alle Linien bedient, die die Haltestelle anfahren und nicht explizit in einer anderen Teilhaltestelle gesetzt sind.
Der Typ Elevator wird in Tabelle 62 beschrieben.
| Feld | Typ |
Beschreibung |
| lines | Liste von strings |
Die Linien, die über diesen Aufzug erreicht werden können. |
| label | string |
Identifiziert den Aufzug an dieser Haltestelle. |
| cabinWidth | integer |
Die Breite der Aufzugskabine (in cm). |
| cabinLength | integer |
Die Tiefe der Aufzugskabine (in cm). |
| doorWidth | integer |
Die Breite der Aufzugstür (in cm). |
| description | string |
Beschreibung des Aufzugs. |
| elevatorType | string |
Der Auzugstyp. |
| buttonType | ElevatorButtonType |
Der Typ der Aufzugsknöpfe. |
| state | ElevatorState |
Der Zustand des Aufzugs. |
| cause | string |
Ein eventueller Grund für den Aufzugszustand. |
Der Typ ButtonType ist ein Enum und kann die Werte BRAILLE, ACUSTIC, COMBI und UNKNOWN annehmen. Der Typ ElevatorState ist ein Enum und kann die Werte READY, OUTOFORDER und UNKNOWN annehmen.
In Listings 33 und 34 werden Zusatzinformationen zur Haltestelle Berliner Tor angefragt.
1{ 2 "version":61, 3 "station": { 4 "id": "Master:10952" 5 } 6}
1{ 2 "returnCode": "OK", 3 "partialStations": [ 4 { 5 "stationOutline": "http://www.geofox.de/images/mobi/stationDescriptions/Berliner_Tor_S_200217_ZM3.jpg" 6 }, 7 { 8 "lines": [ 9 "U2", 10 "U3" 11 ], 12 "stationOutline": "http://www.geofox.de/images/mobi/stationDescriptions/Berliner_Tor_U_200217_ZM3.jpg", 13 "elevators": [ 14 { 15 "lines": [ 16 "U2", 17 "U3", 18 "U4" 19 ], 20 "label": "A", 21 "cabinWidth": 93, 22 "cabinLength": 216, 23 "doorWidth": 90, 24 "description": "Schalterhalle <-> U2 Ri. Niendorf Nord und U3 Ri. Schlump/Barmbek und U4 Ri. HafenCity Universität", 25 "elevatorType": "Durchlader", 26 "buttonType": "COMBI", 27 "state": "READY" 28 }, 29 { 30 "lines": [ 31 "U2", 32 "U3", 33 "U4" 34 ], 35 "label": "B", 36 "cabinWidth": 93, 37 "cabinLength": 216, 38 "doorWidth": 90, 39 "description": "Schalterhalle <-> U2 Ri. Mümmelmannsberg und U3 Ri. Wandsbek Gartenstadt und U4 Ri. Billstedt", 40 "elevatorType": "Durchlader", 41 "buttonType": "COMBI", 42 "state": "READY" 43 }, 44 { 45 "label": "C", 46 "cabinWidth": 93, 47 "cabinLength": 216, 48 "doorWidth": 90, 49 "description": "Zugang Beim Strohhause <-> Schalterhalle", 50 "elevatorType": "Durchlader", 51 "buttonType": "COMBI", 52 "state": "READY" 53 } 54 ] 55 } 56 ], 57 "lastUpdate": { 58 "date": "12.10.2017", 59 "time": "12:33" 60 } 61}
Der TariffZoneNeighboursRequest liefert alle zum HVV gehörenden Tarifzonen und der jeweiligen benachbarten Tarifzonen.
URL: /gti/public/tariffZoneNeighbours
Der TariffZoneNeighboursRequest bietet keine Einstellungsmöglichkeiten.
Der TariffZoneNeighboursResponse wird in Tabelle 63 beschrieben.
Nachfolgend wird ein Beispiel-Request dargestellt.
1{ 2 "tariffZones": [ 3 { 4 "zone": "000", 5 "ring": "A", 6 "neighbours": [ 7 "101", 8 "103", 9 "105", 10 "106", 11 "108" 12 ] 13 }, 14 { 15 "zone": "101", 16 "ring": "A", 17 "neighbours": [ 18 "000", 19 "103", 20 "108", 21 "201", 22 "203", 23 "209" 24 ] 25 }, 26 ... 27 ] 28}
Der TariffMetaDataRequest liefert alle möglichen Ticket-Bereichs-Kombinationen zurück.
URL: /gti/public/tariffMetaData
Im TariffMetaDataRequest kann die anzuzeigende Sprache eingestellt werden (siehe
1.4.)
Der TariffMetaDataResponse wird in Tabelle 64 beschrieben.
| Feld |
Typ |
Beschreibung |
| tariffKinds |
Liste von TariffKind |
Liste der Kartenarten. |
| tariffLevels |
Liste von TariffLevel |
Liste der Tariflevel. |
| tariffCounties |
Liste von TariffCounty |
Liste der Landkreise. |
| tariffZones |
Liste von TariffZone |
Liste der Tarifzonen. |
| tariffRings |
Liste von string |
Liste der Tarifringe. |
Der Typ TariffKind wird in Tabelle 65 beschrieben.
| Feld |
Typ |
Beschreibung |
| id |
integer |
Id der Kartenart. |
| label |
string |
Name der Kartenart. |
| requiresPersonType |
boolean |
Gibt an ob weitere Informationen bezüglich der Person, welche dieses Ticket benutzt, benötigt werden, optional. |
| ticketType |
TicketType |
Gibt an ob das Ticket eine Einzelkarte oder eine Zeitkarte ist (enums SINGLE_TICKET, SEASON_TICKET, optional. |
| levelCombinations |
Liste von integer |
Liste der möglichen Tariflevel-Kombinationen für dieses Ticket, optional. |
Der Typ TariffLevel wird in Tabelle 66 beschrieben.
Der Typ RequiredRegionType wird in Tabelle 67 beschrieben.
Der Typ TariffCounty wird in Tabelle 68 beschrieben.
Der Typ TariffZone wird in Tabelle 69 beschrieben.
Nachfolgend wird ein Beispiel-Request dargestellt.
1{ 2 "tariffKinds": [ 3 { 4 "id": 1, 5 "label": "Einzelkarte", 6 "ticketType": "SIBGLE_TICKET", 7 "levelCombinations": [1, 66, 2, 8, 9, 14, 15, 22, 23, 24, 100, 38, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54] 8 }, ... 9 { 10 "id": 56, 11 "label": "ProfiTicket", 12 "ticketType": "SEASON_TICKET", 13 "levelCombinations": [22, 23 15] 14 }, 15 ... 16 ], 17 "tariffLevels": [ 18 { 19 "id": 1, 20 "label": "1 Tarifzone", 21 "requiredRegionType": { 22 "type": "ZONE", 23 "count": 1 24 } 25 }, ... 26 { 27 "id": 23, 28 "label": "3 Ringe", 29 "requiredRegionType": { 30 "type": "RING", 31 "count": 3 32 } 33 }, ... 34 { 35 "id": 44, 36 "label": "Stadtverkehr Wahlstedt" 37 }, 38 ... 39 ], 40 "tariffCounties": [ 41 { 42 "id": "PI", 43 "label": "Kreis Pinneberg" 44 }, 45 ... 46 ], 47 "tariffZones": [ 48 { 49 "zone": "307", 50 "ring": "B" 51 }, 52 ... 53 ], 54 "tariffRings": [ 55 "A", 56 "B", 57 "C", 58 "D", 59 "E" 60 ] 61}
Die Methode singleTicketOptimizer berechnet unter Berücksichtigung von vorhandenen Zeitkarten für eine Gruppe von Personen die optimale Ticketkombination für eine bestimmte Fahrt (Tarifberater).
URL: /gti/public/singleTicketOptimizer
Der Request wird in Tabelle 70 beschrieben.
| Feld | Typ |
Beschreibung |
| withReturnJourney | boolean |
Fahrkarten für den Rückweg mit einbeziehen |
| numberOfAdults | int |
Anzahl der mitfahrenden Erwachsenen |
| numberOfChildren | int |
Anzahl der mitfahrenden Kinder |
| tickets | Liste von TariffOptimizerTicket |
Liste der vorhandenen Zeitkarten |
| route | Liste von SingleTicketOptimizerRequestRoute |
Die Route für die die Fahrkarten berechnet werden soll |
| Feld | Typ |
Beschreibung |
| tariffKindId | int |
ID der Fahrkartenart |
| tariffKindLabel | string |
Name der Fahrkartenart |
| tariffLevelId | int |
ID der Tarifstufe |
| tariffLevelLabel | string |
Name der Tarifstufe |
| tariffRegions | string |
Tarifbereiche die von dieser Fahrkarte abgedeckt werden |
| regionType | enum TicketRegionType |
Typ der Tarifbereiche (z.B. Tarifzone oder Tarifringe) |
| count | int |
Anzahl Fahrkarten |
| extraFare | boolean |
Gibt an, ob es sich um eine Zuschlagskarte handelt |
| personType | enum TariffPersonType |
Personentyp für den diese Fahrkarte gültig ist |
| centPrice | int |
Fahrkartenpreis in Cent |
| Feld | Typ |
Beschreibung |
| trip | SingleTicketOptimizerRequestTrip |
Teil der Route mit Start, Ziel und Linie |
| departure | dateTime |
Abfahrtszeit der Route |
| arrival | dateTime |
Ankunftszeit der Route |
| tariffRegions | TariffOptimizerRegions |
durchfahrene Tarifbereiche |
| singleTicketTariffLevelId | int |
Einzelkartentarifstufe für die Route |
| extraFareType | TariffExtraFareType |
Zuschlagstyp |
Die SingleTicketOptimizerResponse enthält nur die zu kaufenden Tickets (Tabelle 70).
Die Methode ermöglicht es dem Client, eine Liste aller HVV Tickets abzufragen. Es ist zudem möglich nur die HVV Tickets abzufragen, die an einer, per StationKey übergebenen, Station verkauft werden.
URL: /gti/public/ticketList
Der Request wird in Tabelle 74 beschrieben.
Die Response wird in Tabelle 75 beschrieben.
Der Typ TicketListTicketInfos wird in Tabelle 76 beschrieben.
| Feld |
Typ |
Beschreibung |
| tariffKindID |
int |
ID der Kartenart |
| tariffKindLabel |
string |
Name der Kartenart |
| tariffLevelID |
int |
ID der Tarifstufe |
| tariffLevelLabel |
string |
Name der Tarifstufe |
| tariffGroupID |
int |
ID der Tarifgruppe |
| tariffGroupLabel |
string |
Name der Tarifgruppe |
| regionType |
Enum |
Werte: ZONE, GH_ZONE, RING, COUNTY, ZG, NET |
| selectableRegions |
int |
Anzahl der auswählbaren Regionen des Tickets. Für ’2 Tarifzonen’ wäre es bspw. 2 |
| requiredStartStation |
boolean |
Wenn true wird die Startstation benötigt, um die Gültigkeit zu verifizieren. |
| personInfos |
Liste von PersonInfo |
Enthält Informationen darüber wieviele Personen von einem bestimmten Typ mit der Karte fahren dürfen. |
| validityPeriods |
Liste von ValidityPeriod |
Enthält Informationen über die Gültigkeit des Tickets. |
| variants |
Liste von TicketList- TicketVariant |
Enthält Informationen über die Ticketvarianten. (Beispiel: 1. Klasse Ticket und 2. Klasse Ticket wären zwei verschiedene Ticketvarianten) |
Der Typ PersonInfo wird in Tabelle 77 beschrieben.
Der Typ ValidityPeriod wird in Tabelle 78 beschrieben.
Der Typ TimePeriod wird in Tabelle 79 beschrieben.
| Feld |
Typ |
Beschreibung |
| begin |
string |
Beginn der Gültigkeitsperiode. Format: HH:mm (Enthält ggf. Stunden-Werte > 24. 30:00 Uhr entspricht 06:00 Uhr am nächsten Tag) |
| end |
string |
Ende der Gültigkeitsperiode. Format: HH:mm (Enthält ggf. Stunden-Werte > 24. 30:00 Uhr entspricht 06:00 Uhr am nächsten Tag) |
Der Typ TicketListTicketVariant wird in Tabelle 80 beschrieben.
| Feld |
Typ |
Beschreibung |
| ticketId |
int |
Eindeutige ID der Ticketvariante. Für HVV die eindeutige 8-stellige HVV ticket ID. |
| kaNummer |
int |
KA-Nummer des Tickets. |
| price |
double |
Der Ticketpreis. (Brutto) |
| currency |
string |
Die Währung des Preises. Wenn nicht angegeben ist EUR gemeint. |
| ticketClass |
Enum |
Werte: NONE, SECOND, FIRST, SCHNELL. |
| discount |
Enum |
Werte: NONE, ONLINE, SOCIAL. |
| validityBegin |
date |
Das Startdatum der Gültigkeit der Tariffdaten dieses Tickets. |
| validityEnd |
date |
Das Enddatum der Gültigkeit der Tariffdaten dieses Tickets. |
1{ 2 "ticketInfos": [ 3 { 4 "tariffKindID": 1, 5 "tariffKindLabel": "Einzelkarte", 6 "tariffLevelID": 14, 7 "tariffLevelLabel": "Hamburg AB", 8 "tariffGroupID": 1, 9 "tariffGroupLabel": "Einzelkarten", 10 "regionType": "GH", 11 "requiredStartStation": false, 12 "personCount": 1, 13 "validityPeriods": [ 14 { 15 "day": "WEEKDAY", 16 "timeValidities": [ 17 { 18 "begin": "00:00", 19 "end": "30:00" 20 } 21 ] 22 }, 23 { 24 "day": "WEEKEND", 25 "timeValidities": [ 26 { 27 "begin": "00:00", 28 "end": "30:00" 29 } 30 ] 31 } 32 ], 33 "variants": [ 34 { 35 "ticketId": 11014100, 36 "kaNummer": 12027, 37 "price": 5.4, 38 "ticketClass": "FIRST", 39 "discount": "NONE", 40 "validityBegin": "2019-03-01T00:00:00.000+0100", 41 "validityEnd": "2019-12-31T00:00:00.000+0100" 42 }, 43 ... 44 ] 45 }, 46 ..., 47 { 48 "tariffKindID": 23, 49 "tariffKindLabel": "9-Uhr-Gruppenkarte", 50 "tariffLevelID": 24, 51 "tariffLevelLabel": "4 Ringe", 52 "tariffGroupID": 2, 53 "tariffGroupLabel": "Tageskarten", 54 "regionType": "RING", 55 "selectableRegions": 4, 56 "requiredStartStation": false, 57 "personCount": 5, 58 "validityPeriods": [ 59 { 60 "day": "WEEKDAY", 61 "timeValidities": [ 62 { 63 "begin": "00:00", 64 "end": "06:00" 65 }, 66 { 67 "begin": "09:00", 68 "end": "30:00" 69 } 70 ] 71 }, 72 { 73 "day": "WEEKEND", 74 "timeValidities": [ 75 { 76 "begin": "00:00", 77 "end": "30:00" 78 } 79 ] 80 } 81 ], 82 "variants": [ 83 { 84 "ticketId": 13624100, 85 "kaNummer": 20225, 86 "price": 26.5, 87 "ticketClass": "FIRST", 88 "discount": "NONE", 89 "validityBegin": "2019-03-01T00:00:00.000+0100", 90 "validityEnd": "2019-12-31T00:00:00.000+0100" 91 }, 92 { 93 "ticketId": 13624107, 94 "kaNummer": 20227, 95 "price": 25.71, 96 "ticketClass": "FIRST", 97 "discount": "ONLINE", 98 "validityBegin": "2019-03-01T00:00:00.000+0100", 99 "validityEnd": "2019-12-31T00:00:00.000+0100" 100 }, 101 ... 102 ] 103 }, 104 ... 105 ] 106}
Die folgenden Abschnitte geben Vorschläge zur Implementierung der Signaturerstellung und Verarbeitung von JSON-Nachrichten in verschiedenen Umgebungen.
Es wird die Bibliothek CommonCrypto/CommonHMAC.h benötigt.
1NSString *password = @"password"; 2NSString *data = @"Request-Message"; 3 4const void *bytesKey = [password cStringUsingEncoding:NSUTF8StringEncoding]; 5const void *bytesData = [data cStringUsingEncoding:NSUTF8StringEncoding]; 6unsigned char cHMAC[CC_SHA1_DIGEST_LENGTH]; 7CCHmac(kCCHmacAlgSHA1, bytesKey, strlen(bytesKey), bytesData, strlen(bytesData), cHMAC); 8NSData *hmacSignature = [NSData dataWithBytes:cHMAC length:CC_SHA1_DIGEST_LENGTH]; 9//Base64 Kodierung der HMACSHA1-Signatur
Die benötigten Methoden zur Serialisierung von JSON werden sowohl vom JSON-Framework2 als auch von TouchJSON3 bereitgestellt, beide können mit NSDictionary-Objekten umgehen. Es wird TouchJSON empfohlen.
1#import "CJSONSerializer.h" 2#import "CJSONDeserializer.h" 3 4//Serialisierung 5NSString *jsonString = [[NSString alloc] initWithString:[[CJSONSerializer serializer] serializeDictionary:request_dictionary]]; 6 7//Deserialisierung 8NSError *error = nil; 9NSDictionary *dictionary = [[CJSONDeserializer deserializer] deserializeAsDictionary:jsonResponseString error:&error];
Für Java und PHP gibt es Beispielimplementierungen unter https://github.com/HBTGmbH/gti-example-clients.
1def _get_signature(request_body: Dict) -> bytes: 2 """ Private function that creates the signature for geofox request. """ 3 key = bytes("the given geofox password", "utf-8") 4 hashed = hmac.new(key, bytes(json.dumps(request_body), "utf-8"), sha1) 5 signature = base64.b64encode(hashed.digest()) 6 return signature
Hinweis: Sowohl während der Signaturerstellung als auch für das Senden des Requests muss der Request (request_body) als JSON-String (json.dumps()) vorliegen.
1function createSignature(requestBody: object): string { 2 const hmac = crypto.createHmac(’sha1’, ’the given geofox password’); 3 hmac.update(JSON.stringify(requestBody)); 4 return hmac.digest(’base64’); 5}
Zur praktischen Umsetzung folgen Hinweise.
Das Feld id in SDName bezeichnet verschiedene Typen von SDNames unterschiedlich genau. SDNames vom Typ STATION werden über eine ID eindeutig identifiziert. Mit dem Typ ADDRESS werden Straßen identifiziert, wobei der Mittelpunkt der Straße als Punkt dieses SDNames betrachtet wird. Möchte man eine postalische Adresse speichern, ist zusätzlich zur ID eine Hausnummer nötig, diese ist dann im Feld name zu übergeben, von wo sie herausgeparst wird.
Orte vom Typ POI werden über die ID eindeutig identifiziert. Koordinaten (Typ COORDINATE) haben keine IDs.
Ein SDName wird über die Felder id, type und combinedName eindeutig identifiziert, wobei statt combinedName auch die Kombination aus name und city gültig ist.
Es gibt Veränderungen an den Haltestellen des Systems, die ab und zu zusammengelegt, aufgeteilt oder gestrichen werden müssen. Dies passiert nicht häufig, aber häufiger, als die Intuition vermuten könnte. Um sicherzustellen, dass die Methoden stets mit aktuellen und damit verwertbaren SDNames aufgerufen werden, gibt es zwei Möglichkeiten:
Der Station Cache ist aktuell zu halten und es wird empfohlen, bei jedem Start der Clientanwendung mit einem init die aktuelle Version der Daten im Feld dataID zu erfragen. Stimmt diese nicht mit der des Station Cache überein, ist dieser mittels listStations zu aktualisieren. Auch an den Linien (Typ LineListEntry) kann es Veränderungen geben, die jedoch seltener als die an Stationen sind. Da das Versionsfeld dataID den gesamten Geofox-Datenbestand versioniert, sind bei Änderung alle Caches des Clients zu aktualisieren. Es ist daher auch möglich, dass trotz unterschiedlicher Versionsnummern auf Update-Anfrage für einen Cache keine aktualisierten Datensätze zurückgegeben werden.
Zusätzlich zu den Methoden wird ein Dienst bereitgestellt, über den einige Standard-Icons des HVV im PNG-Format abgerufen werden können.
Die Icons teilen sich in die drei Arten: Vehicle Icons, Line Icons und Miscellaneous Icons. Bei jedem Abruf eines Icons ist die gewünschte Höhe in Pixeln als Parameter anzugeben, zulässige Werte sind zwischen 10 und 100 Pixel. Manche Pixel sind transparent.
Ein Vehicle Icon steht allgemein für Fahrzeugtypen (Verkehrsmittel) wie z.B. U- oder S-Bahn.
Eine Besonderheit ist, daß mehrere einzelne Vehicle Icons in einer Grafik gezeigt werden können. Damit ist es mit nur einem Icon möglich, die verschiedenen Verkehrsmittel einer Haltestelle darzustellen, wie z.B. im Vorschlager von Geofox. Die erzeugten Bilder sind immer quadratisch. Als Parameter ist eine Liste von Vehikeln zu übergeben, die durch Semikolon zu trennen sind. Durch den Parameter varSize=true wird das Bus-Symbol größer dargestellt, als die Anderen. Dies kompensiert die geringere Fläche. Da Vehicle Icons auch über die ServiceTypes angesprochen werden können, sind in der Tabelle 82 teilweise Alternativen angegeben. Es ist somit beispielsweise möglich das AKN-Symbol über den Eintrag abahn oder über den ServiceType a anzufragen.
In Tabelle 82 werden die zulässigen Werte von vehicle beschrieben.
| Eintrag | Vehicle | Icon |
| abahn oder a | AKN |  |
| sbahn oder s | S-Bahn |  |
| ubahn oder u | U-Bahn |  |
| rbahn oder r | Regionalbahn |  |
| fbahn oder train | Fernbahn |  |
| bus | Bus |  |
| faehre oder ship | Hafenfähre |  |
| ast | Anruf-Sammel-Taxi |  |
| fbus | Fernbus |  |
| rb | Regionalbahn |  |
| re | Regionalexpress |  |
| schnellbus | Schnellbus |  |
| ice | ICE |  |
| Fussweg | Fußweg |  |
Ein Line Icon beinhaltet sowohl die Nummer der Linie, als auch in seiner Darstellung die Art der Linie.
In Tabelle 83 werden einige Beispiele gezeigt.
Ein Linien-Icon kann mithilfe des lineKey, der DLID oder des Linien-Namens abgerufen werden. Zur Verwendung des LineKey muss der /line Endpunkt mit dem Parameter lineKey aufgerufen werden, für DLIDs gibt es den /dlid Endpunkt mit dem Parameter dlid und Linien-Namen können über den Endpunkt /linename mit dem Parameter name verwendet werden. Alle drei Endpunkte haben zusätzlich folgende Parameter:
| Parameter |
Beschreibung |
| height |
Höhe des Icons (min. 10, max. 150) |
| outlined (Optional) |
Wenn der Hintergrund transparent ist (bspw. bei Regionalbahnen), soll die Schrift des Icons mit einem weißen Rahmen versehen werden? (default: false) |
| fileFormat (Optional) |
Format des Icons (mögliche Werte: PNG, SVG. default: PNG) |
| appearance (Optional) |
Erscheinungsbild des Icons (mögliche Werte: COLOURED, MONOCHROME. default: COLOURED) |
Hier finden sich weitere Icons, die eventuell von Nutzen sein können. Auch sind die Fahrzeugtypen aus
den Vehicle Icons aufgenommen worden, da einige Icons länglich sind und diese hier, anders
als bei den quadratischen Vehicle Icons, auch länglich dargestellt werden. Ein Beispiel
ist:
https://cloud.geofox.de/icon/misc?name=busWide&height=60
Die zulässigen Werte für misc werden in Tabelle 85 beschrieben.
| Parameter | Bedeutung | Icon |
| abahn | AKN | |
| sbahn | S-Bahn | |
| ubahn | U-Bahn | |
| rbahn | Regionalbahn | |
| fbahn | Fernbahn | |
| bus | Bus | |
| busWide | Bus, z.B. als Symbol für viele einzelne Buslinien | |
| faehre | Hafenfähre | |
| bike | Fahrradweg |  |
| foot | Fußweg | |
| ast | Anruf-Sammel-Taxi | |
| fbus | Fernbus | |
| rb | Regionalbahn | |
| re | Regionalexpress | |
| schnellbus | Schnellbus | |
| ice | ICE | |
Fehler werden auf zwei verschiedenen Kanälen übermittelt: Zum einen werden die HTTP-Status-Codes im HTTP-Header genutzt, zum anderen hat jede Response (weil sie von BaseResponseType erbt) Felder zur Fehlerbehandlung, die sich im HTTP-Body befinden.
Diese beziehen sich jedoch nur auf die Kommunikation und nicht auf den Inhalt; ein HTTP-Status-Code 200 OK stellt also keine erfolgreiche Verarbeitung des Request (inhaltlich) sicher.
Die HTTP-Status-Codes sind Tabelle 86 zu entnehmen.
|
Status-Code im HTTP-Header |
Fehlerbeschreibung |
|
400 Bad Request |
Anfrage ungültig (z.B. XML-Parser-Fehler oder ungültige IDs im Request) |
|
401 Unauthorized |
Authentifizierung, z.B. Signatur ungültig, IP nicht gewhitelistet |
|
403 Forbidden |
Zugriff nicht erlaubt |
|
429 Too Many Requests |
Zu viele Zugriffe pro Zeit. Dieser Fehler sollte im Normalbetrieb nicht auftreten, da der Zugriffsschutz (wie auch der von geofox.de) für eine übliche Häufigkeit ausgelegt ist. Sollte es doch Probleme geben, kann zusammen mit der HBT GmbH eine Lösung gefunden werden |
|
500 Internal Server Error |
Programmfehler im GTI |
|
503 Service Unavailable |
Backendsystem nicht erreichbar |
|
200 OK |
Kommunikation zunächst fehlerfrei, evtl. jedoch inhaltliche Fehler. |
Die in der Response übermittelten Fehler- und Statuscodes werden in Tabelle 87 beschrieben.
|
Feld |
Wert |
Beschreibung |
|
returnCode |
OK |
Keine Fehler |
|
|
ERROR_CN_TOO_MANY |
checkName liefert zu viele Treffer (Suchbegriff ist zu präzisieren) |
|
|
ERROR_COMM |
Verbindungsfehler beim Backend-Zugriff |
|
|
ERROR_ROUTE |
Es konnte keine Route berechnet werden |
|
|
ERROR_TEXT |
Verweis auf die zusätzlichen Felder errorText und errorDevInfo |
|
|
START_NOT_FOUND |
Starthaltestelle nicht gefunden |
|
|
DEST_NOT_FOUND |
Zielhaltestelle nicht gefunden |
|
|
VIA_NOT_FOUND |
Viahaltestelle nicht gefunden |
|
|
FORCED_START_NOT_FOUND |
erzwungene Starthaltestelle nicht gefunden |
|
|
FORCED_DEST_NOT_FOUND |
erzwungene Zielhaltestelle nicht gefunden |
|
errorText |
Optionale,
für
den
Benutzer
bestimmte
Volltext-Fehlermeldung
(in
der
im
Request
angegebenen
Sprache,
sofern
vorhanden)
| |
|
errorDevInfo |
Für
den
Entwickler
bestimmte
Fehlermeldung
mit
detaillierteren
Informationen
(z.B.
aufgetretene
Exceptions)
| |
Im Feld errorDevInfo werden oft technische Details geantwortet, im Fehlerfall immer – auch im Fall von Fehlern, die per HTTP-Status gemeldet werden. In Tabelle 88 werden Beispiele für mögliche Kombinationen Fehler/HTTP Code gegeben.
|
Fehler |
HTTP-Code und Felder des Bodies |
|
Programmierfehler im Client: In der Anfrage ist ein Syntaxfehler, der zu einem Fehler beim Unmarshalling (von JSON oder XML) führt |
Status
Code:
400
Bad
Request
|
|
Programmierfehler im Client: Die Anfrage ist syntaktisch wohlgeformt, aber semantisch fehlerhaft, z.B. ein checkName mit leerem Feld theName (Typ SDName) |
Status
Code:
400
Bad
Request
|
|
Programmierfehler im GTI-Server, es tritt eine interne Exception auf |
Status
Code:
500
Internal
Server
Error
|
|
Ungültige Haltestellen-ID im Request |
Status
Code:
400
Bad
Request
|
|
Datum |
API-Version |
Doc-Version |
Autor |
Änderung |
|
26.05.2025 |
61 |
1 |
tkr, jma |
stopPoint in Departure ergänzt und coordinateType in DLRequest ergänzt. |
|
28.04.2025 |
60 |
1 |
jma |
Felder für hvv TicketID ergänzt |
|
23.08.2024 |
59 |
2 |
jma |
starts und dests müssen nun gefüllt sein bei getIndividualRoute |
|
15.08.2024 |
59 |
1 |
km, bas |
SDName enthält nun das Feld address. Wird nur für POIs gefüllt. |
|
29.07.2024 |
58 |
2 |
jma, bas |
SDName enthält nun das Feld provider, welches bei Activity-Stations gefüllt ist. Bei ACTIVITY_BIKE_AND_RIDE steht die Provider-Info nun auch in dem line-Element. |
|
10.07.2024 |
58 |
1 |
jma, bas |
SimpleServiceType enthält nun den Typ ACTIVITY_BIKE_AND_RIDE. getRoute kann nun Bike and Ride Stationen bei der Suche berücksichtigen |
|
21.05.2024 |
57 |
1 |
bas |
getRoute liefert nun Informationen zu den Fahrzeugen, die eine Fahrt durchführen |
|
30.04.2024 |
56 |
3 |
bas |
(zu Version 58.1 verschoben) |
|
30.04.2024 |
56 |
2 |
bas |
(zu Version 57.1 verschoben) |
|
06.03.2024 |
56 |
1 |
jma |
Zonen werden nur für Ergebnisse außerhalb Hamburg AB und bei maximal 2 Zonen ausgegeben |
|
20.11.2023 |
55 |
5 |
bw |
Neue returnCodes START_NOT_FOUND, DEST_NOT_FOUND, VIA_NOT_FOUND, FORCED_START_NOT_FOUND, FORCED_DEST_NOT_FOUND |
|
29.08.2023 |
55 |
4 |
jsc |
IntermediateStops zu ScheduleElementLight in getTariff hinzugefügt |
|
04.08.2023 |
55 |
3 |
kd |
Code-Beispiele für Java und PHP durch Link zum Beispiel-Repository ersetzt |
|
24.07.2023 |
55 |
2 |
bw |
travelTimetable entfernt |
|
06.04.2023 |
55 |
1 |
kd, bas |
neues Feld announcements zu ScheduleElement hinzugefügt. Ab Version 55 werden Announcements in diesem neuen Feld ausgeliefert, und nicht mehr über attributes |
|
31.03.2023 |
54 |
1 |
kd, jma |
neue Felder blacklist und groups in den TariffInfoSelector-Objekten hinzugefügt. Neues Feld tariffInfoSelector zu TariffRequest hinzugefügt |
|
05.08.2022 |
53 |
1 |
kd |
neues Feld layer in den SDName-Objekten hinzugefügt |
|
05.08.2022 |
52 |
1 |
jma |
neues Feld dlid in den Service-Objekten in getAnnouncements |
|
28.07.2022 |
51 |
1 |
jek |
neues Feld withPaths in getRoute |
|
07.03.2022 |
50 |
1 |
jp |
neues Feld regionTexts in TariffResponse |
|
07.03.2022 |
49 |
2 |
mag |
neue URL für Soll Fahrplan |
|
07.03.2022 |
49 |
1 |
jma |
IDs für Start/Ziel-Haltestellen bei Tickets ergänzt |
|
07.03.2022 |
48 |
1 |
jfo |
SH-Tarif Überwege ergänzt |
|
08.11.2021 |
47 |
1 |
mag |
Aussagekräftigere Fehlercodes |
|
06.09.2021 |
46 |
2 |
hvo |
Korrektur GTI URL |
|
25.08.2021 |
46 |
1 |
mag |
Neues Feld für für den öffentlichen Rundfunk relevante Meldungen in getAnnouncement |
|
18.08.2021 |
45 |
1 |
mag |
line in getRoute hat neue Felder für Betreibernamen |
|
22.07.2021 |
44 |
1 |
mag, bw, sth |
Tarifzonen und Orts-Ids für den SH-Tarif in checkName-Response ergänzt, geplante und tatsächliche Abfahrts- und Ankunftszeiten in den Schedules der getRoute-Response hinzugefügt. |
|
16.06.2021 |
43 |
1 |
mag |
Attributes in getRoute haben neues Feld id |
|
26.04.2021 |
42 |
1 |
sth |
CheckName-Request unterstützt jetzt Deutschlandweite Haltestellen-IDs (DHID) |
|
12.04.2021 |
41 |
1 |
hvo |
Tags von Fußwegen werden in IndividualRoute zurückgeliefert. |
|
12.04.2021 |
40 |
1 |
hvo |
Zeiten von IntermediateStops werden immer im Format HH:mm zurückgeliefert. |
|
10.03.2021 |
39 |
1 |
jma |
direction-Feld bei Departures in der DLResponse hinzugefügt. |
|
02.03.2020 |
38 |
1 |
bw,jma |
XpressBus hinzugefügt. |
|
17.01.2020 |
37 |
5 |
bw |
singleTicketTariffOptimizer ergänzt, Fehler korrigiert. |
|
08.01.2020 |
37 |
4 |
bw |
TariffOptimizer entfernt. |
|
22.10.2019 |
37 |
3 |
fj |
Abschnitte zur Zugriffsbeschränkung und Inaktivität hinzugefügt. |
|
21.08.2019 |
37 |
2 |
ie |
Maximale Distanz für Reverse Geocoding ergänzt. |
|
08.08.2019 |
37 |
1 |
chb |
Neue Methode ticketList hinzugefügt. |
|
01.07.2019 |
36 |
2 |
bw |
Codebeispiele Python und Typescript ergänzt. CNRequest max Werte ergänzt. |
|
23.01.2019 |
36 |
1 |
bw |
Feld shopInfo zum ScheduleElement hinzugefügt. |
|
23.01.2019 |
35 |
1 |
ie, bw |
Neuen Request TariffZoneNeighboursRequest hinzugefügt. |
|
18.12.2018 |
34 |
1 |
fp |
Neuer Wert für Gleisgleiche Umstiege in Enum SimpleServiceType hinzugefügt. |
|
22.10.2018 |
33 |
1 |
lj |
Neues Feld version in Announcement (Tabelle 45) hinzugefügt. |
|
01.06.2018 |
32 |
1 |
ie |
Neue Felder notRecommended und shopLink in TicketInfo (Tabelle 24) hinzugefügt. |
|
04.05.2018 |
31 |
5 |
chb |
Icons wurden aktualisiert. Tabelle 82 beinhaltet nun ServiceTypes als Alternative (a,s,r,u,Fussweg,ship) |
|
23.01.2018 |
31 |
4 |
chb |
Zusätzliche Erklärung zur contSearch mit contSearchByServiceId in Abhängigkeit der timeIsDeparture hinzugefügt. |
|
12.10.2017 |
31 |
3 |
chb |
GRResponse lieft nun auch die Linien-Richtung als DirectionId. |
|
12.10.2017 |
31 |
2 |
chb |
Beispiele aktualisiert. Java Signaturerstellung verbessert. Allgemeine Verbesserung der Übersichtlichkeit. |
|
07.08.2017 |
31 |
1 |
ie |
Koordinaten in getIndividualRoute korrigiert. KM-Methoden entfernt. |
|
07.04.2017 |
30 |
7 |
lj |
Neues Feld in DLRequest für mehrere Haltestellen hinzugefügt. |
|
26.10.2016 |
30 |
6 |
kd |
Neue Attributstypen für Echtzeitprognosen hinzugefügt. |
|
06.09.2016 |
30 |
5 |
kd |
Fehler in der Beschreibung der neuen Suchoptionen behoben. |
|
29.08.2016 |
30 |
4 |
kd |
Fehler im Enum VehicleType behoben. |
|
23.08.2016 |
30 |
3 |
ie |
getVehicleMap und getTrackCoordinates veröffentlicht. |
|
13.07.2016 |
30 |
2 |
kd |
icon_service um Parameter varSize ergänzt. |
|
06.07.2016 |
30 |
1 |
kd |
Announcement und AnnouncementRequest um zusätzliche Filtermöglichkeiten erweitert |
|
08.06.2016 |
29 |
1 |
kd |
GRRequest und GRResponse erweitert für besseres Cont-Search Verhalten unter Echtzeit. |
|
31.03.2016 |
28 |
1 |
kd |
Methode getStationInformation mit StationInformationRequest und StationInformationResponse implementiert. |
|
14.01.2016 |
27 |
1 |
kd |
„Neue Suchoptionen” für www.geofox.de implementiert. |
|
07.12.2015 |
26 |
2 |
kd,bw |
„X-Platform”-HTTP-Header hinzugefügt. WADL-Adresse korrigiert. |
|
25.11.2015 |
26 |
1 |
kd |
Methode checkPostalCode mit PCRequest und PCResponse hinzugefügt. |
|
21.09.2015 |
25 |
1 |
sku,kd |
Hinweis auf Individualprofile und attributierte Pfade in Abschnitt 2.10 hinzugefügt. |
|
21.08.2015 |
24 |
1 |
kd,ie |
Attribut model zu den Typen ServiceType und CourseElement hinzugefügt. IntermediateStops in GRRequest/GRResponse hinzugefügt. |
|
07.07.2015 |
23 |
1 |
bw |
Attribute zum DepartureCourse (DCResponse) und zum Departure (DLResponse) hinzugefügt |
|
03.03.2015 |
22 |
6 |
bw |
Dokumentation zu Echtzeit in öffentliche Doku übernommen, PHP-Beispiel ergänzt, Layout verbessert |
|
03.03.2015 |
22 |
5 |
bw |
HVVGTI und GTI zu einer Anwendung mit unterschiedlichen URLs zusammen geführt. |
|
09.12.2014 |
22 |
4 |
bw |
Dokumentation zum Verkehrsmittelfilter in departureList hinzugefügt. |
|
12.11.2014 |
22 |
3 |
kd |
Methode getVehicleMap aufgeteilt in getVehicleMap und getTrackCoordinates. |
|
19.08.2014 |
22 |
2 |
bw |
Veralteten Fehlercode START_DEST_TOO_CLOSE entfernt. |
|
19.08.2014 |
22 |
1 |
bw |
Verkehrsmittelfilter zur Abfahrtstafel hinzugefügt, Methode getAnnouncements erweitert. |
|
14.08.2014 |
21 |
3 |
kd |
Dokumentation für icon_service um Line Icons erweitert. |
|
11.08.2014 |
21 |
2 |
bw |
Flag returnPartialTickets hinzugefügt. |
|
06.06.2014 |
21 |
1 |
bw |
Echtzeit Gleisangaben eingefügt. |
|
10.01.2014 |
20 |
1 |
kd,bw |
Abschnitt 2.4.3 zur Filterung des DLRequests hinzugefügt. |
|
10.01.2014 |
19 |
1 |
ie |
Methode getIndividualRoute in HVVGTI hinzugefügt. Option mit Fahrrad auch am Ziel hinzugefügt. ReturnCode START_DEST_TOO_CLOSE hinzugefügt. |
|
18.12.2013 |
19 |
X |
bw |
Echtzeit Erweiterung (getRoute, departureList, departureCourse) |
|
05.12.2013 |
18 |
4 |
kd |
Neuformatierung in LaTeX |
|
20.11.2013 |
18 |
3 |
tw |
getRoute-Beschreibung berichtigt, Icon Service berichtigt |
|
04.11.2013 |
18 |
2 |
jp |
getVehicleMap hinzugefügt |
|
27.08.2013 |
18 |
1 |
pk |
ticketRemarks hinzugefügt, Ticket deprecated gesetzt |
|
20.08.2013 |
17 |
2 |
pk |
Icon Service hinzugefügt |
|
15.08.2013 |
17 |
1 |
bw |
ListStations Äquivalenzfilter, VehicleType Fernbahn, SimpleServiceType Bicycle |
|
29.07.2013 |
16 |
3 |
bw |
Beschreibung zu penalties DesiredType und DesiredCarrier verbessert |
|
24.05.2013 |
16 |
2 |
pk |
Neuverfassung der Dokumentation in zwei Subversionen (hvvgti und gti) |
|
23.01.2012 |
16 |
1 |
bw |
ermäßigte Preise für elektronische Fahrkarten & vehicleTypes im CNRequest |
|
08.01.2012 |
15 |
2 |
bw |
ReturnCodes ERROR_XX entfernt |
|
05.12.2012 |
15 |
1 |
bw |
Neues Fehlerkonzept für KM, Properties im KMRouteRequest, TraceID |
|
15.11.2012 |
14 |
3 |
bw |
MobilityProvider UNSPECIFIED eingefügt |
|
24.10.2012 |
14 |
2 |
bw |
Komplementäre Mobilität und IndividualRoute hinzugefügt |
|
31.08.2012 |
14 |
1 |
bw |
regionType in TicketInfo, TariffRegionType „GH_ZONE” eingefügt. |
|
23.08.2012 |
13 |
3 |
fw |
DCRequest/DCResponse hinzugefügt |
|
21.08.2012 |
13 |
2 |
bw |
Feld-Typ f. tariffInfoSelector korrigiert |
|
19.07.2012 |
13 |
1 |
bw |
Tarifinformationen aus Tarif Response in Get Route Response integrieren. |
|
14.06.2012 |
12 |
1 |
bw |
ScheduleElements als Umstiegsfußwege zwischen den normalen ScheduleElements eingefügt. |
|
13.06.2012 |
11 |
1 |
bw |
Gleisinformationen in platform umbenannt (vorher track) |
|
31.05.2012 |
10 |
1 |
bw |
Track (Gleis) zu Departure hinzugefügt. track (Gleis) aus SDName nach JourneySDName verschoben. |
|
16.03.2012 |
9 |
1 |
ie |
track (Gleis) zu SDName hinzugefügt. |
|
14.03.2012 |
8 |
2 |
cg |
Einleitung neu formuliert und auf IP-Authentifizierung hingewiesen. |
|
23.01.2012 |
8 |
1 |
ie |
schedulesBefore und schedulesAfter in getRoute hinzugefügt. |
|
01.09.2011 |
7 |
1 |
bw |
AnnouncementRequest implementiert, Fahrt-ID, Linien-IDs und Haltestelle in Abfahrtstafel. |
|
05.08.2011 |
6 |
1 |
bw |
Einfeldsuche und typenlose Suche |
|
01.08.2011 |
5 |
1 |
bw |
Auswechslung des JSON Parsers und damit nicht Abwärtskompatible Änderung des JSON-Formats. Einfügen einiger Beispiele. |
|
07.07.2011 |
4 |
1 |
bw |
Linien IDs für die TariffRequests eingefügt |
|
19.05.2011 |
3 |
1 |
rei |
Type zum Attribute hinzugefügt |
|
04.05.2011 |
2 |
1 |
bw |
ScheduleElement um einen Path erweitert, sodass Fußwege übertragen werden können. |
|
24.06.2010 |
1 |
1 |
kha |
Initialversion |
1XML basiertes Dateiformat zur Beschreibung von REST-Webservices, analog zur WSDL
2http://code.google.com/p/json-framework/
