GTI Anwenderhandbuch Version 38.1

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.

1.1 Format und Felder eines HTTP-Paketes

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

Tabelle 1: Felder eines Geofox-HTTP-Paketes


X-Platform	Beschreibung

ios	für iOS Apps

android	für Android Apps

winphone	für Windows Phone Apps

web	für Desktop Webseiten

mobile	für mobile Webseiten

Tabelle 2: Mögliche Werte für X-Platform

Listing 1: HTTP-Post

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: api-test.geofox.de
11Connection: Keep-Alive
12
13{}

1.1.1 TraceID (UUID)

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.

1.2 Formate zur Codierung des HTTP-Bodys

Die Kommunikation (Requests und Responses) im HTTP-Body kann in den Formaten JSON oder XML codiert sein.

1.2.1 JSON

1.2.2 XML

1.3 Authentifikation

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.

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.

1.4 Request und Response

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.

1.4.1 Feld version: API-Version

Ü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.

1.4.2 Feld language: Systemsprache

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.

1.4.3 Feld filterType: Datenfilter

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.

1.4.4 Felder parsen

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.

1.5 Fachbegriffe des ÖPNV

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.

1.6 Datenformate

1.6.1 Datumsformate (date, time, GTITime, dateTime)

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.

1.6.2 Koordinaten und ihr Format

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.

1.6.3 Line Keys

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.

1.6.4 Zeitumstellung

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.

1.6.5 Exakte Dokumentation in der WADL

Auf https://api-test.geofox.de/gti/public?_wadl&_type=xml ist eine Beschreibung des GTI im Format WADL (Web App Description Language¹) 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.

1.7 Soll-Fahrplan

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.

1.8 Echtzeit

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.

1.9 Inaktivität

1.10 Zugriffsbeschränkung

Benutzern, welche im Schnitt mehr als einen API-Aufruf pro Sekunde tätigen, wird der API-Zugang temporär gesperrt.

1.11 Funktionsübersicht


Methode, URL	Beschreibung

Init /gti/public/init	Abrufen allgemeiner Systeminformationen

checkName /gti/public/checkName	Finden von für das System verwertbaren Orten

getRoute /gti/public/getRoute	Finden einer optimalen Route

departureList /gti/public/departureList	Finden der Abfahrten einer Haltestelle

getTariff /gti/public/getTariff	Finden von Tarif-Informationen zu einer Route

departureCourse /gti/public/departureCourse	Anfragen des Verlaufes (Haltestellenabfolge) einer Fahrt

listStations /gti/public/listStations	Ermöglicht Erstellung und Pflege eines Haltestellen-Caches im Client

listlines /gti/public/listLines	Anfragen aller Linien, die seit einer Datenversion eine Änderung erfahren haben

getAnnouncements /gti/public/getAnnouncements	Anfragen von aktuellen Bekanntmachungen wie Fahrplanabweichungen

checkPostalCode /gti/public/checkPostalCode	Überprüfung, ob eine Postleitzahl im HVV Gebiet liegt

getVehicleMap /gti/public/getVehicleMap	Gibt alle Fahrzeuge und deren Bewegung in einer bestimmten Gegend zu einer bestimmten Zeit zurück

getTrackCoordinates /gti/public/getTrackCoordinates	Gibt die Koordinaten zu bestimmten Streckenabschnitten zurück

getIndividualRoute /gti/public/getIndividualRoute	Komplementäre Mobilität: Finden einer optimalen individuellen Route

getStationInformation /gti/public/getStationInformation	Abruf zusätzlicher Informationen einer Haltestelle

tariffMetaData /gti/public/tariffMetaData	Liefert diverse statische Tarif-Informationen

singleTicketOptimizer /gti/public/singleTicketOptimizer	Tarifberater für Gruppen

ticketList /gti/public/ticketList	Liefert eine Liste der Fahrkarten im HVV mit diversen Eigenschaften

Tabelle 3: Methoden des aktuellen APIs

1.12 Klassendiagramme

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.

2 Bereitgestellte Methoden

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".

2.1 Methode init

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.

2.1.1 Beispiel

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.

Listing 6: InitRequest

1{}

Listing 7: InitResponse

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}

2.2 Methode checkName

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.

2.2.1 CNRequest

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

Tabelle 4: CNRequest

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

Tabelle 5: Der Enum SDType


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)

Tabelle 6: Die Felder von SDName


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

Tabelle 7: Die Felder des Typs TariffDetails (in SDName)

2.2.2 CNResponse

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.

2.2.3 Beispiel

In Listings 8 und 9 werden Ergebnisse zum Begriff „Christuskirche” angefragt. Eine Haltestelle wird gefunden, die mit ihren Details zurückgegeben wird.

Listing 8: CNRequest zum Begriff „Christuskirche“

1{
2 "version":38,
3 "theName":{
4 "name":"Christuskirche",
5 "type":"UNKNOWN"
6 },
7 "maxList":1,
8 "coordinateType":"EPSG_4326"
9}

Listing 9: CNResponse zum Begriff „Christuskirche“

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}

2.3 Methode getRoute

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)

Tabelle 8: GRRequest

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.

2.3.1 ContinousSearch

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.


Vorhaben	ContSearchByServiceId-Typ	TimeIsDeparture

Vorherigen Route suchen	contSearchBefore	false

Nächste Route suchen	contSearchAfter	true

Tabelle 9: ContSearch-TimeIsDeparture Zusammenhang

2.3.2 Tarifinformationen

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.

Tabelle 10: TariffInfoSelector

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

Tabelle 11: Liste der verfügbaren HVV-Karten

2.3.3 Penalties

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)

Tabelle 12: Die Penalties

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 (Umsteigen)	Werte	Bedeutung der Werte	Bemerkung

ChangeEvent (Umsteigen)	0 4 8 20	gern, wenn schneller normal ungern vermeiden	Default: normal, 4

ExtraFare (Zuschlag)	0 10 20 50	gern, wenn schneller normal ungern vermeiden	Default: normal, 10

Walker (Fußweg)	0 1 3 8	gern, wenn schneller normal ungern vermeiden	Default: normal, 1

AnyHandicap (Mobilität)	-1 0 1 2 3 4 5	gut zu fuß normal langsam sehr langsam mit Traglast ohne Treppe ohne Treppe/Stufe	Default: normal, 0

ToStartStationBy (Weg zur Haltestelle)	0 1 7	zu Fuß mit Fahrrad mit Fahrrad auch am Ziel	Default: zu Fuß, 0

TimeRange (Zeitvorgabe)	10 20 30 45 60	sehr groß groß normal gering sehr gering	Default: normal, 30 Je größer dieser Wert, desto weniger werden Abweichungen vom Vorgabewert akzeptiert.

ForVisitors (Ortsfremd, zus. Umsteigezeit)	0 1	nein ja	Default:nein, 0

DesiredType (Verkehrsmitteltyp)	-10 -2 0 2 10 10000	unbedingt bevorzugen neutral ungern vermeiden ausschließen	Default: 0 Mögliche Verkehrsmittel: siehe DesiredType

DesiredLine (Linien)	2 1	bevorzugen vermeiden	kein Default. Kombinationen wie {"name":"DesiredLine", "value":"u2,s1:1"} sind möglich.

DesiredCarrier (Betreiber)	2 0 1	bevorzugen neutral vermeiden	Default: neutral, 0 Es kann nur ein Betreiber angegeben werden. Mögliche Betreiber: siehe DesiredCarrier

Tabelle 13: Mögliche Penaltytypen und ihre Werte

2.3.4 DesiredType

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

Tabelle 14: DesiredType Fahrzeugtypen

2.3.5 DesiredCarrier

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

2.3.6 Beispiel der Umsetzung auf geofox.hvv.de

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 Hohe Geschwindigkeit	AnyHandicap=-1

Beste Verbindung Normale Geschwindigkeit	Default, keine extra Penalties

Beste Verbindung Niedrige Geschwindigkeit	AnyHandicap=1

Schnellste Verbindung Hohe Geschwindigkeit	AnyHandicap=-1 ChangeEvent=0 Walker=0 ExtraFare=0

Schnellste Verbindung Normale Geschwindigkeit	ChangeEvent=0 Walker=0 ExtraFare=0

Schnellste Verbindung Niedrige Geschwindigkeit	AnyHandicap=1 ChangeEvent=0 Walker=0 ExtraFare=0

Rollstuhl	ExtraFare=0 AnyHandicap=5

Tabelle 15: Vergleich http://geofox.hvv.de-Optionen/Penalties

2.3.7 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

Tabelle 16: GRResponse

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)

Tabelle 17: Schedule

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

Tabelle 18: ScheduleElement


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.

Tabelle 19: ContSearchByServiceId

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

Tabelle 20: Service

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.

Tabelle 21: JourneySDName


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

Tabelle 22: TariffInfo

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.

Tabelle 23: TicketInfo

2.3.8 Echtzeit

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).

2.3.9 Beispiel

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.

Listing 10: GRRequest

1{
2   "version": 38,
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": "Kellinghusenstrae",
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}

Listing 11: GRResponse

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       },
87       "paths": [
88         {
89          "track": [
90            {
91             "x": 10.240837,
92             "y": 53.683063
93            },
94            {
95             "x": 10.240822,
96             "y": 53.683063
97            },
98            ...
99          ]
100         }
101       ],
102       "attributes": [
103         {
104          "value": "Test-Meldung für das Gesamtnetz",
105          "types": [
106            "ANNOUNCEMENT"
107          ]
108         }
109       ],
110       "serviceId": 60848
111      },
112      {
113       "from": {
114         "name": "U Ahrensburg West",
115         "city": "Ahrensburg",
116         "combinedName": "U Ahrensburg West",
117         "id": "Master:34009",
118         "type": "STATION",
119         "coordinate": {...},
120         "serviceTypes": [
121          "bus",
122          "u"
123         ],
124         "hasStationInformation": false,
125         "depTime": {
126          "date": "17.10.2017",
127          "time": "13:45"
128         }
129       },
130       "to": {
131         "name": "Ahrensburg West",
132         "city": "Ahrensburg",
133         "combinedName": "Ahrensburg West",
134         "id": "Master:34900",
135         "type": "STATION",
136         "coordinate": {...},
137         "serviceTypes": [
138          "bus",
139          "u"
140         ],
141         "hasStationInformation": true,
142         "arrTime": {
143          "date": "17.10.2017",
144          "time": "13:47"
145         }
146       },
147       "line": {
148         "name": "Umstiegsfuweg",
149         "type": {
150          "simpleType": "CHANGE"
151         }
152       }
153      },
154      ...
155    ]
156   }
157 ],
158 "individualTrack": {
159   "time": 371,
160   "length": 25562,
161   "type": "FOOTPATH"
162 }
163}

2.4 Methode departureList

Die Methode departureList liefert die Abfahrten an einer gegebenen Haltestelle in einem gegebenen Zeitintervall.

2.4.1 DLRequest

URL: /gti/public/departureList

Die Felder des Requests sind in Tabelle 24 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.

Tabelle 24: DLRequest

2.4.2 DLResponse


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

Tabelle 25: DLResponse


Feld	Typ	Beschreibung

line	Service	Name, direction, type und ID des Verkehrsmittels, siehe GRResponse

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

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)

Tabelle 26: Departure

2.4.3 Filter

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)

Tabelle 27: FilterEntry

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 28 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

Tabelle 28: Fahrzeugtypen für den Verkehrsmittelfilter

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.

2.4.4 Beispiel

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.

Listing 12: DLRequest

1{
2 "version": 38,
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}

Listing 13: DLResponse

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}

Listing 14: DLRequest

1{
2 "version": 38,
3 "stations": [
4   {
5    "name": "Gro Flottbeker Strae",
6    "city": "Hamburg",
7    "combinedName": "Gro Flottbeker Strae",
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}

2.5 Methode getTariff

2.5.1 TariffRequest

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 29 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

Tabelle 29: TariffRequest


Feld	Typ	Beschreibung

departureStationId	string	Haltestellen-Id der Starthaltestelle

arrivalStationId	string	Haltestellen-Id der Endhaltestelle

lineId	string	Id der Linie

Tabelle 30: Die Felder von ScheduleElementLight

2.5.2 TariffResponse

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 31 beschrieben.


Feld	Typ	Beschreibung

tariffName	String	Die Region des Tarifs (z.B. HVV, HL, SH)

extraFareType	Enum	NO: Es wird kein Zuschlag benötigt POSSIBLE: Erste Klasse Zuschlag ist möglich. REQUIRED: Zuschlag ist zwingend erforderlich

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 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

Tabelle 31: TariffInfo

2.5.3 Beispiel

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.

Listing 15: TariffRequest

1{
2 "language": "de",
3 "version": 38,
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}

Listing 16: TariffResponse

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}

2.6 Methode departureCourse

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 32 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

Tabelle 32: DCRequest

2.6.1 DCResponse

Die DCResponse enthält eine Liste courseElements von CourseElements. Der Typ CourseElement wird in Tabelle 33 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)

Tabelle 33: CourseElement

2.6.2 Beispiel

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.

Listing 17: DCRequest

1{
2 "language": "de",
3 "version": 38,
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}

Listing 18: DCResponse

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}

2.7 Methode listStations

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.

2.7.1 LSRequest

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 34 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)

Tabelle 34: LSRequest

2.7.2 LSResponse

Die Response wird in Tabelle 35 beschrieben. Der Typ StationListEntry wird in Tabelle 36 beschrieben.


Feld	Typ	Beschreibung

dataReleaseID	string	Version der aktuellen Daten

stations	Liste von StationListEntry	Die Daten: Stationen, die sich geändert haben

Tabelle 35: LSResponse


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

Tabelle 36: StationListEntry

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.

2.7.3 Beispiel

Listing 19: LSRequest

1{
2 "language": "de",
3 "version":38,
4 "dataReleaseID": "29.73.01",
5 "modificationTypes": ["MAIN"]
6}

Listing 20: LSResponse

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}

2.8 Methode listLines

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.

2.8.1 LLRequest


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

Tabelle 37: LLRequest

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.

2.8.2 LLResponse


Feld	Typ	Beschreibung

dataReleaseID	string	Version der aktuellen Daten

lines	Liste von LineListEntry	Die Daten: Linien, die sich geändert haben.

Tabelle 38: LLResponse

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.

Tabelle 39: LineListEntry


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

Tabelle 40: SublineListEntry


Feld	Typ	Beschreibung

id	string	ID der Haltestelle

name	string	Der Name der Haltestelle

Tabelle 41: StationLight

2.8.3 Beispiel

Listing 21: LLRequest

1{
2 "language": "de",
3 "version": 38,
4 "dataReleaseID": "29.71.01",
5 "modificationTypes": ["MAIN"]
6}

Listing 22: LLResponse

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}

2.9 Methode getAnnouncements

2.9.1 AnnouncementRequest

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 42 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)

Tabelle 42: AnnouncementRequest

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.

2.9.2 AnnouncementResponse

Die AnnouncementResponse enthält den Zeitpunkt der letzten Aktualisierung und eine Liste der einzelnen Meldungen. Sie wird in Tabelle 43 beschrieben.


Feld	Typ	Beschreibung

announcements	Liste von Announcement	Liste aller angefragten Meldungen

lastUpdate	dateTime	Zeitpunkt der letzten serverseitigen Aktualisierung

Tabelle 43: AnnouncementResponse


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. (siehe Tabelle 45).

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 46 aufgezählt. (seit API Version 30)

Tabelle 44: Announcement

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 45 beschrieben.


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 52).

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.

Tabelle 45: Location


Wert

UNDEFINED_PROBLEM

ROADWORKS

CONGESTION

SPECIAL_EVENT

SLIPPERINESS

POLICE_REQUEST

FIRE_BRIGADE_SAFETY_CHECKS

STATION_OVERRUN

SERVICE_FAILURE

ROAD_CLOSED

VEHICLE_ON_THE_LINE

ACCIDENT

DEMONSTRATION

STAFF_ABSENCE

BOMB_ALERT

LOW_WATER_LEVEL

ROUTE_BLOCKAGE

ROUGH_SEA

Tabelle 46: Announcement.Reason

2.9.3 Beispiel

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.

Listing 23: AnnouncementRequest

1{
2 "language": "de",
3 "version": 38,
4 "names": [
5 "S3"
6 ],
7 "full": true
8}

Listing 24: AnnouncementResponse

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       },
20       "begin": {
21         "name": "Poppenbüttel",
22         "city": "Hamburg",
23         "combinedName": "Poppenbüttel",
24         "id": "Master:71953",
25         "type": "STATION"
26       },
27       "end": {
28         "name": "Wedel",
29         "city": "Wedel",
30         "combinedName": "Wedel",
31         "id": "Master:85950",
32         "type": "STATION"
33       }
34      },
35      {
36       "type": "SINGLE_LINE",
37       "line": {
38         "name": "S11",
39         "direction": "Poppenbüttel",
40         "origin": "Blankenese",
41         "type": {
42          "simpleType": "TRAIN",
43          "shortInfo": "S",
44          "longInfo": "S-Bahn"
45         },
46         "id": "ZVU-DB:S11_ZVU-DB_S-ZVU"
47       },
48       "begin": {
49         "name": "Poppenbüttel",
50         "city": "Hamburg",
51         "combinedName": "Poppenbüttel",
52         "id": "Master:71953",
53         "type": "STATION"
54       },
55       "end": {
56         "name": "Blankenese",
57         "city": "Hamburg",
58         "combinedName": "Blankenese",
59         "id": "Master:81950",
60         "type": "STATION"
61       }
62      },
63      ...
64    ],
65    "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.",
66    "publication": {
67      "begin": "2015-01-01T13:00:00.000+0100",
68      "end": "2017-10-12T10:00:00.000+0200"
69    },
70    "validities": [
71      {
72       "begin": "2017-10-12T08:00:00.000+0200",
73       "end": "2017-10-12T10:00:00.000+0200"
74      }
75    ],
76    "lastModified": "2017-10-12T08:34:55.877+0200"
77   },
78   ...
79 ],
80 "lastUpdate": "2017-10-12T08:34:55.877+0200"
81}

2.10 Methode getIndividualRoute

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.

2.10.1 IndividualRouteRequest

URL: /gti/public/getIndividualRoute

Der IndividualRouteRequest wird in Tabelle 47 beschrieben.


Feld	Typ	Name

starts	Liste von SDName	Liste der Startpunkte

dests	Liste von SDName	Liste der Zielpunkte

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

Tabelle 47: IndividualRouteRequest

Feld

BICYCLE_NORMAL

BICYCLE_RACING

BICYCLE_QUIET_ROADS

BICYCLE_MAIN_ROADS

BICYCLE_BAD_WEATHER

FOOT_NORMAL

Tabelle 48: IndividualProfileType

2.10.2 IndividualRouteResponse

Die IndividualRouteResponse besteht aus einer Liste von IndiviualRoutes die in Tabelle 49 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

Tabelle 49: IndiviualRoute

2.10.3 Beispiel

Listing 25: IndividualRouteRequest

1{
2 "version": 38,
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}

Listing 26: IndividualRouteRespose

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}

2.11 Methoden getVehicleMap und getTrackCoordinates

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.

2.11.1 VehicleMapRequest


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

Tabelle 50: VehicleMapRequest

Eine BoundingBox enthällt 2 Coordinate: lowerLeft & upperRight, welche zwischen sich ein Gebiet eingrenzen (in der GIS-Sprache: Envelope oder BoundingBox)

2.11.2 VehicleMapResponse

Die Response besteht aus einer Liste von Journey(Fahrten), die in Tabelle 51 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 52 beschrieben

vehicleType	VehicleType	Der Fahrzeugtyp, mit dem diese Linie betrieben wird. Mögliche Werte sind in Tabelle 55 aufgezählt.

realtime	Boolean	Zeigt an, ob die Daten echtzeitbehaftet sind

segments	Liste von PathSegment	Die Streckenabschnitte

Tabelle 51: Journey


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. 53 beschrieben

id	String	ID der Linie

Tabelle 52: Service


Feld	Typ	Name

simpleType	SimpleServiceType	Type der Linie, Eine Auzählung, die in Tab. 54 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)

Tabelle 53: ServiceType