GTI Anwenderhandbuch
öffentlicher Teil
Version 38.1
für API-Version 38
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.
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.
In Listing 3 wird ein Beispiel für eine CNResponse im JSON-Format gegeben.
Listing 4 zeigt ein Beispiel für ein CNRequest im XML-Format.
Listing 5 zeigt ein Beispiel für ein CNResponse im XML-Format.
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":{"x":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://api-test.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://sfds.geofox.de/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.
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 |
Liefert zur angegebenen Koordinate die nächstgelege 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 |
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) |
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 |
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.
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) |
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 (z.B. HVV, SH). Der Wert all gibt Informationen über alle bekannten Tarife zurück (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 werden alle gültigen Karten zurückgegeben. |
Die Liste der verfügbaren HVV-Karten (kinds) wird nur selten verändert. Mit Stand von 2012-07 sind diese in 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.
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 |
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. 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.). |
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) |
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 52 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) klassifiziert den Typ des Service, zwei Strings shortInfo und longInfo beschreiben ihn |
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 TariffInfo (der GRResponse) wird in Tabelle 22 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 23 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 |
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. |
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.