Erweiterungen für Google Transit-Tickets

Auf dieser Seite wird die Teilmenge der GTFS-Ticketspezifikation definiert, die sich beim Erstellen dieses Dokuments in der Entwurfsphase befindet. Auf dieser Seite findest du außerdem einige zusätzliche Einschränkungen von Google.

Voraussetzungen

Das Feld departure_time in stop_times.txt ist ein Pflichtfeld.

Zusätzliche Feldtypen

In diesem Abschnitt werden die zusätzlichen Feldtypen sowie die mit Erweiterungen von Google beschrieben.

• URI: Ein voll qualifizierter URI (Uniform Resource Identifier), der das Schema enthält. Für alle Sonderzeichen im URI müssen die korrekten Escapezeichen verwendet werden. Eine Beschreibung zum Erstellen voll qualifizierter URI-Werte findest du unter RFC 3986 Uniform Resource Identifier (URI): Generic Syntax.

Dateierweiterungen oder -hinzufügungen

Dateiname	Status	Definition
agency.txt	Erweiterung	Fügt agency.ticketing_deep_link_id hinzu
routes.txt	Erweiterung	Fügt routes.ticketing_deep_link_id hinzu
trips.txt	Erweiterung	Fügt trips.trip_ticketing_id, trips.ticketing_type hinzu
stop_times.txt	Erweiterung	Fügt stop_times.ticketing_type hinzu
ticketing_identifiers.txt	Hinzufügung
ticketing_deep_links.txt	Hinzufügung

Tabellendefinitionen

agency.txt (Datei erweitert)

Feldname	Präsenz	Details
ticketing_deep_link_id	Optional	(ID aus ticketing_deep_links.txt) Definiert den Deeplink, der für diesen Betreiber verwendet werden soll. Kann in routes.txt überschrieben werden.

routes.txt (Datei erweitert)

Feldname	Präsenz	Details
ticketing_deep_link_id	Optional	(ID aus ticketing_deep_links.txt) Definiert den Deeplink, der für diese Route verwendet werden soll. Falls vorhanden, wird der Wert in agency.txt überschrieben.

trips.txt (Datei erweitert)

Feldname	Präsenz	Details
ticketing_trip_id	Optional	(ID) Kennung, die im Deeplink übergeben werden soll. Muss nicht eindeutig sein. Ein Fallback auf trip_id erfolgt.
ticketing_type	Optional	(Enum) Lege fest, ob Tickets über Deeplinks für diese Fahrt verfügbar sind: Für 0 oder empty wird Folgendes vorausgesetzt: Verfügbar, wenn „ticketing_deep_link_id“ für die Route oder den Betreiber definiert ist. Andernfalls nicht verfügbar. 1: Nicht verfügbar.

stop_times.txt (Datei erweitert)

Feldname	Präsenz	Details
ticketing_type	Optional	(Enum) Gib an, ob Tickets über Deeplinks für diese Fahrt verfügbar sind. Falls definiert, überschreibe den in trip.ticketing_type festgelegten Wert. Leer: wie von trip.ticketing_type definiert. 0: Annahme: Verfügbar, wenn für die Route oder den Betreiber ticketing_deep_link_id definiert ist. Andernfalls nicht verfügbar. Wichtig: Wenn für einen bestimmten stop_id-Wert einer der dazugehörigen stop_times-Elemente die Einstellung ticketing_type=1 hat, müssen alle anderen stop_times auch ticketing_type=1 haben.

ticketing_identifiers.txt (Datei hinzugefügt)

In einem Ticketsystem ist es meistens so, dass jede Haltestelle eine Kennung für die Verarbeitung der Abrechnung hat. Unterschiedliche Betreiber verwenden unter Umständen dieselbe Kennung für eine bestimmte Haltestelle. Wenn mehrere Betreiber dieselbe Haltestelle bedienen, wiederhole diese Zuordnung für jeden Betreiber.

Feldname	Präsenz	Details
ticketing_stop_id	Erforderlich	(ID) Lege eine standardmäßige Ticket-ID für diese Haltestelle dieses Betreibers fest.
stop_id	Erforderlich	(ID aus stops.txt) Die Haltestelle, für die der Standardwert vonticketing_stop_id definiert wird.
agency_id	Erforderlich	(ID aus agency.txt) Der Betreiber der Haltestelle, für den der Standardwert von ticketing_stop_id definiert wird.

ticketing_deep_links.txt (Datei hinzugefügt)

Feldname	Präsenz	Details
ticketing_deep_link_id	Erforderlich	(ID) Gib eine ID für den Deeplink an.
web_url	Optional	(URL) Die URL, die für Deeplinks aufgerufen werden soll. Übersetzungen können über translations.txt erfolgen, um Fahrgäste an gebietsspezifische URLs weiterzuleiten.
android_intent_uri	Optional	(URI) Der URI, der an eine native Android-App mit dem Intent „android.intent.action.VIEW“ übergeben werden soll. Ein leerer URI bedeutet, dass keine Deeplinks zu einer nativen Android-App vorhanden sind. Wichtig: Für dieses Feld wird die URL-Übersetzung nicht unterstützt. Daher muss die Spracherkennung von der empfangenden Website/App erfolgen. Weitere Informationen zu Deeplinks unter Android findest du unter Create Deep Links to App Content. Empfehlung: Verwende Android-App-Links, die sowohl sicherer als auch besser funktionieren als Fallbacks, wenn der Fahrgast die native Android-App nicht auf seinem Gerät installiert hat. Dieses Feld kann nicht über translations.txt übersetzt werden.
ios_universal_link_url	Optional	(URL) Die universelle Link-URL, die unter iOS aufgerufen wird. Wichtig: Für dieses Feld wird die URL-Übersetzung nicht unterstützt. Daher muss die Spracherkennung von der empfangenden Website/App erfolgen. Wenn das Feld leer ist, wird der Deeplink unter iOS nicht angezeigt. Weitere Informationen zu universellen Links unter iOS Dieses Feld kann nicht über translations.txt übersetzt werden.

Best Practice: Wenn für mehrere Betreiber/Routen dieselben Deeplink-URLs genutzt werden, empfehlen wir dringend, nur einen Deeplink zu definieren und alle diese Betreiber/Routen mit demselben Deeplink zu verknüpfen.

Feldplatzhalter im API-Aufruf

Google ruft die vorherigen URLs mit den folgenden Parametern auf:

Feldname	Präsenz	Details
service_date	Erforderlich	(Datum, wiederholbar) Betriebstag der Fahrt. Dieses Feld wird als JSON-Array formatiert.
ticketing_trip_id	Erforderlich	(ID aus trips.txt, wiederholbar) Die ID der Fahrt. Dieses Feld wird als JSON-Array formatiert.
from_ticketing_stop_time_id	Erforderlich	(Wiederholbar) Kennung von stop_time, zu der der Streckenabschnitt beginnt. Für eine bestimmte Haltestellenzeit ist der Wert: Die in der Datei ticketing_identifiers.txt definierte ticketing_stop_id für „agency_id“ und die „stop_id“ für „stop_time“. Wichtig: Dabei werden die ticketing_identifiers nur für die Haltestelle selbst verwendet. Selbst wenn die Haltestelle eine übergeordnete Haltestelle hat, werden die ticketing_identifiers der übergeordneten Haltestelle ignoriert. Andernfalls wird stop_sequence als Fallback verwendet. Dieses Feld wird als JSON-Array formatiert.
to_ticketing_stop_time_id	Erforderlich	(Wiederholbar) Kennung von stop_time, zu der der Streckenabschnitt endet. Eine Erläuterung zur Ableitung des Werts findest du unter from_ticketing_stop_time_id. Dieses Feld wird als JSON-Array formatiert.
boarding_time	Erforderlich	(ISO 8601, wiederholbar) Die Abfahrtszeit (departure_time) von stop_time, zu der der Streckenabschnitt beginnt. Der Zeitwert dieses Felds entspricht ISO 8601 mit folgendem Formatstring: YYYY-MM-DDThh:mm:ss±hh:mm Alle unten angegebenen Zeiten sind in verschiedenen Zeitzonen gleich: In London, Vereinigtes Königreich: 2019-07-29T18:26:00+01:00 In New York, USA: 2019-07-29T13:26:00-04:00 In Tokio, Japan: 2019-07-30T02:26:00+09:00 Wichtig: Die Zeitzone für den Betreiber im Feed muss nicht unbedingt dieselbe Zeitzone sein. Die Zeitzone ist in UTC angegeben. Dieses Feld wird als JSON-Array formatiert.

Beispiele

Wenn das die Streckenabschnitte sind:

• Am Betriebstag 20190716 Fahrtticket-ID ti1 von Haltestellenzeit-Ticket-ID 11 bis Haltestellenzeit-Ticket-ID 12, Einstieg um 14:00 Uhr UTC
• Am Betriebstag 20190716 Fahrtticket-ID ti2 von Haltestellenzeit-Ticket-ID 21 bis Haltestellenzeit-Ticket-ID 22, Einstieg um 15:00 Uhr UTC

Und web_url ist: http://meinebuchungswebsite.de

Die Werte der Parameter sind:

Feldname	Details
service_date	["20190716", "20190716"]
ticketing_trip_id	["ti1", "ti2"]
from_ticketing_stop_time_id	["11", "21"]
to_ticketing_stop_time_id	["12", "22"]
boarding_time	["2019-07-16T14:00:00+00:00", "2019-07-16T15:00:00+00:00"]

Der endgültige URI (nach der Codierung) ist:

http://myawesomebookingwebsite.com?service_date=%5B%2220190716%22,%22%2019071622%5D &ticketing_trip_id=%5B%22ti1%22,%22ti2%22%5D&from_ticketing_stop_time_id=%5B%2211%22,%2221%22%5D &to_ticketing_stop_time_id=%5B%2212%22,%2222%22%5D&boarding_time=%5B%222019-07-16T14:00:00%2B00:00 %22,%222019-07-16T15:00:00%2B00:00%22%5D

Beispiele für verschiedene ticketing_stop_id-Werte

Haltestellen können unterschiedliche IDs haben, um über das Feld ticketing_identifiers.txt Tickets zu erstellen. Die fett formatierten Werte sind die im Webaufruf nach den Dateien beschriebenen Werte.

stop.txt
stop_id,stop_name si1,"Paris Gare-de-Lyon" si2,"Lyon Part-Dieu"

routes.txt
route_id,route_long_name,ticketing_deep_link_id ri1,"TGV inOui Paris-Lyon",tdl1

trips.txt
trip_id,service_id,route_id,trip_short_name, ticketing_trip_id ti1,everyday,ri1,"TGV INOUI 6603",FR_SNCF_6603 ti2,everyday,ri1,"TGV INOUI 6681",FR_SNCF_6681 ti3,everyday,ri1,"TGV INOUI 6607",FR_SNCF_6607

stop_times.txt
trip_id,stop_sequence,stop_id,arrival_time, departure_time ti1,1,si1,06:59:00,06:59:00 ti1,2,si2,08:56:00,08:56:00 ti2,1,si1,07:53:00,07:53:00 ti2,2,si2,10:00:00,10:00:00 ti3,1,si1,08:59:00,08:59:00 ti3,2,si2,10:56:00,10:56:00

ticketing_identifiers.txt
stop_id,agency_id,ticketing_stop_id si1,agency1,4924 si2,agency1,4676

ticketing_deep_links.txt
ticketing_deep_link_id, web_url, android_intent_url, ios_universal_urltdl1, https://www.thetrainline.com/api/gtfs/web, https://www.thetrainline.com/api/gtfs/android, https://www.thetrainline.com/api/gtfs/ios

Der Aufruf für das Web lautet so, wenn die Anfrage am 19. Juli 2019 initiiert wurde und die GTFS-Zeiten in der Zeitzone UTC+1 angegeben sind:

http://www.thetrainline.com/api/gtfs/web?service_date=%5B%2220190719%22%5D&ticketing_trip_id= %5B%22FR_SNCF_6603%22%5D&from_ticketing_stop_time_id=%5B%224924%22%5D&to_ticketing_stop_time_id= %5B%224676%22%5D&boarding_time=%5B%222019-07-19T07:59:00%2B00:00%22%5D

Wichtig: Der Wert in boarding_time (UTC) entspricht nicht unbedingt der Zeitzone in GTFS (UTC+1). Es kann also eine Verschiebung der Zeitzone im Wert HH:MM:SS entstehen.