Google Transit-Fahrkartenerweiterungen

Auf dieser Seite wird ein Teil der GTFS-Fahrkartenspezifikation definiert, die sich beim Erstellen dieses Dokuments noch in der Entwurfsphase befand. Außerdem enthält diese Seite 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 und diejenigen mit Erweiterungen von Google beschrieben. Für einige Felder sind Werte in Form eines URI erforderlich.

• URI: Ein voll qualifizierter URI (Uniform Resource Identifier) mit dem Schema. Alle Sonderzeichen im URI müssen korrekt maskiert werden. Eine Beschreibung zum Erstellen voll qualifizierter URI-Werte ist unter RFC 3986 Uniform Resource Identifier (URI): Generic Syntax verfügbar.

Dateierweiterungen oder ‑ergänzungen

Die Textdateien mit dem Status Erweiterung sind Dateien, die bereits vorhanden sind und die erweitert werden müssen. Dazu müssen Sie die Felder hinzufügen, die in der folgenden Tabelle definiert sind.

Die Textdateien mit dem Status Ergänzung sind neue Dateien, die aufgrund der Google Transit-Fahrkartenerweiterungen erforderlich werden. Sie müssen diese Dateien gemäß den Felddefinitionen erstellen, die unter der folgenden Tabelle verfügbar sind. Diese Dateien müssen in Ihrem Feed enthalten sein.

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 und trips.ticketing_type hinzu.
stop_times.txt	Erweiterung	Fügt stop_times.ticketing_type hinzu.
ticketing_identifiers.txt	Ergänzung	Neue Datei. Weitere Informationen finden Sie unter Felddefinitionen.
ticketing_deep_links.txt	Ergänzung	Neue Datei. Weitere Informationen finden Sie unter Felddefinitionen.

Felddefinitionen

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. Hinweis: Wenn Sie den Fahrkartenverkauf auf den gesamten statischen Feed anwenden möchten, müssen Sie in der Datei agency.txt im Feld ticketing_deep_link_id für alle Betreiber denselben Wert festlegen.

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 damit das Feld 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. Wenn ticketing_trip_id leer ist, verwendet das System stattdessen den Wert von trip_id.
ticketing_type	Optional	(Enum) Legen Sie fest, ob der Fahrkartenverkauf für diese Fahrt über einen Deeplink verfügbar ist: 0 oder leer: Wenn Sie eine ticketing_deep_link_id für die Route oder den Betreiber definieren, ist der Fahrkartenverkauf verfügbar. Sonst nicht. 1: Nicht verfügbar.

stop_times.txt (Datei erweitert)

Feldname	Präsenz	Details
ticketing_type	Optional	(Enum) Gibt an, ob der Fahrkartenverkauf für diese Haltestellenzeit über einen Deeplink verfügbar ist. Wenn Sie stop_times.ticketing_type definieren, wird dadurch der in trip.ticketing_type festgelegte Wert überschrieben. Leer: Verwendet den Wert von trip.ticketing_type. 0: Wenn Sie eine ticketing_deep_link_id für die Route oder den Betreiber definieren, ist der Fahrkartenverkauf verfügbar. Sonst nicht. 1: Nicht verfügbar. Wichtig: Wenn ein stop_times-Wert einer bestimmten stop_id auf ticketing_type=1 gesetzt ist, müssen alle anderen stop_times auch ticketing_type=1 haben.

ticketing_identifiers.txt (Datei hinzugefügt)

Beim Fahrkartenverkauf 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) Definiert eine standardmäßige Fahrkarten-ID für diese Haltestelle und diesen Betreiber.
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) Definiert eine ID für den Deeplink.
web_url	Optional	(URL) Die Ziel-URL, die für den Deeplink verwendet werden soll. Dieses Feld kann nicht über translations.txt übersetzt werden. Wichtig: Für dieses Feld wird die URL-Übersetzung nicht unterstützt. Daher muss die Spracherkennung auf der Ziel-Website bzw. in der Ziel-App erfolgen.
android_intent_uri	Optional	(URI) Der URI, der an eine native Android-App mit dem Intent android.intent.action.VIEW übergeben werden soll. Wenn das Feld leer ist, können Sie keinen Deeplink zu einer nativen Android-App erstellen. Wichtig: Für dieses Feld wird die URL-Übersetzung nicht unterstützt. Daher muss die Spracherkennung auf der Ziel-Website bzw. in der Ziel-App erfolgen. Weitere Informationen zu Deeplinks unter Android sind unter Deeplinks zu App-Inhalten erstellen verfügbar. Empfehlung: Verwenden Sie Android-App-Links. Sie sind sicherer und funktionieren besser 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 auf der Ziel-Website bzw. in der Ziel-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.

Hinweis: Wenn im Feed dieselben Deeplink-URLs für mehrere Betreiber oder Routen verwendet werden, empfehlen wir dringend, nur einen Deeplink für alle zu definieren. Weitere Informationen finden Sie im Abschnitt Best Practices.

Platzhalter für Felder im API-Aufruf

Google ruft die in ticketing_deep_links.txt definierten URLs mit den folgenden Parametern auf:

Feldname	Details
service_date	(Datum, wiederholbar) Der Betriebstag der Fahrt. Dieses Feld wird als JSON-Array formatiert.
ticketing_trip_id	(ID aus trips.txt, wiederholbar) Die ID der Fahrt. Dieses Feld wird als JSON-Array formatiert.
from_ticketing_stop_time_id	(Wiederholbar) Die Kennung der Haltestellenzeit (stop_time), zu der der Streckenabschnitt beginnt. Für eine bestimmte Haltestellenzeit lautet der Wert: ticketing_stop_id, definiert in ticketing_identifiers.txt für agency_id und stop_id von 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	(Wiederholbar) Die Kennung der stop_time, zu der der Streckenabschnitt endet. Eine Erläuterung zur Ableitung des Werts finden Sie unter from_ticketing_stop_time_id. Dieses Feld wird als JSON-Array formatiert.
boarding_time	(ISO 8601, wiederholbar) Die Abfahrtszeit (departure_time) von stop_time, zu der der Streckenabschnitt beginnt. Der Wert für die Zeit in diesem Feld entspricht ISO 8601 mit folgendem Stringformat: YYYY-MM-DDThh:mm:ss±hh:mm Die Angaben unten entsprechen derselben Zeit in verschiedenen Zeitzonen: 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 entspricht nicht unbedingt der Zeitzone des Betreibers im Feed. Sie wird in UTC angegeben. Dieses Feld wird als JSON-Array formatiert.
arrival_time	(ISO 8601, wiederholbar) Ankunftszeit (arrival_time) zur „stop_time“, zu der der Streckenabschnitt endet. Der Wert für die Zeit in diesem Feld entspricht ISO 8601 mit folgendem Stringformat: YYYY-MM-DDThh:mm:ss±,hh:mm Die Angaben unten entsprechen derselben Zeit in verschiedenen Zeitzonen: In London, Vereinigtes Königreich: 2019-07-29T18:46:00+01:00 In New York City, USA: 2019-07-29T13:46:00-04:00 In Tokio, Japan: 2019-07-30T02:46:00+09:00 Wichtig: Die Zeitzone entspricht nicht unbedingt der Zeitzone des Betreibers im Feed. Sie wird in UTC angegeben. Dieses Feld wird als JSON-Array formatiert.

Beispiele

In diesem Beispiel sehen Sie die Streckenabschnitte der Fahrt eines Fahrgastes:

• Am Betriebstag 20190716 beginnt die Fahrkarten-ID ti1 von der Fahrkarten-ID der Haltestellenzeit 11 und endet mit der Fahrkarten-ID der Haltestellenzeit 12. Der Fahrgast steigt um 14:00 Uhr (UTC) ein und kommt um 14:50 Uhr (UTC) an.
• Am Betriebstag 20190716 beginnt die Fahrkarten-ID ti2 von der Fahrkarten-ID der Haltestellenzeit 21 und endet mit der Fahrkarten-ID der Haltestellenzeit 22. Der Fahrgast steigt um 15:00 Uhr (UTC) ein und kommt um 15:50 Uhr (UTC) an.

In diesem Beispiel ist https://examplepetstore.com die web_url.

Unter Berücksichtigung all dieser Informationen verwenden Sie die folgenden Werte für die Parameter des Feeds für diese Fahrt:

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"]
arrival_time	["2019-07-16T14:50:00+00:00", "2019-07-16T15:50:00+00:00"]

Nach der Codierung sieht der endgültige URI so aus:

https://examplepetstore.com?service_date=%5B%2220190716%22,%2220190716%22%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&arrival_time=%5B%222019-07-16T14:50:00%2B00:00 %22,%222019-07-16T15:50:00%2B00:00%22%5D

Beispiele für verschiedene Werte für ticketing_stop_id

Haltestellen können unterschiedliche IDs für den Fahrkartenverkauf über das Feld ticketing_identifiers.txt haben. 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_uri, ios_universal_link_url tdl1, https://examplepetstore.com/api/gtfs/web, https://examplepetstore.com/api/gtfs/android, https://examplepetstore.com/api/gtfs/ios

Wenn die Anfrage am 19.07.2019 erfolgt und die GTFS-Zeiten in der Zeitzone UTC+1 angegeben sind, lautet der Aufruf für das Web:

https://examplepetstore.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-19T05:59:00%2B00:00%22%5&arrival_time=%5B%222019-07-19T07:56:00%2B00:00%22%5D

Wichtig: Die Werte in boarding_time und arrival_time (in UTC) entsprechen nicht unbedingt der Zeitzone in der GTFS (UTC+1). Das führt zu einer Abweichung des HH:MM:SS-Werts.

Best Practices

Folgen Sie diesen Empfehlungen, um Google Transit-Fahrkartenerweiterungen zu implementieren:

Richtlinien
Verwenden Sie nach Möglichkeit dieselben Deeplinks für Betreiber oder Routen.	Wenn im statischen Feed dieselben Deeplink-URLs für mehrere Betreiber oder Routen verwendet werden, muss auch ihr Wert im Feld ticketing_deep_link_id gleich sein. Dies ermöglicht Umstiege zwischen Betreibern oder Routen. Hinweis: Andernfalls müssen Fahrgäste zwei getrennte Tickets kaufen, da die Werte in ticketing_deep_link_id unterschiedlich sind.
Legen Sie einheitliche Werte für ticketing_type fest.	Der Wert für ticketing_type für eine bestimmte Haltestelle muss in allen Zeilen der Datei stop_times.txt gleich sein. Hinweis: Wenn für ticketing_type der Wert 1 festgelegt ist, wird der Fahrkartenverkauf für alle Fahrten mit dieser Haltestelle deaktiviert.
Weisen Sie ticketing_stop_id sowohl übergeordneten als auch untergeordneten Haltestellen zu.	Führen Sie die Zuweisung für alle übergeordneten und untergeordneten Haltestellen durch, für die Fahrkarten erforderlich sind. In der Datei ticketing_identifiers.txt werden die ticketing_stop_id-Werte nicht zwischen übergeordneten und ihren untergeordneten Haltestellen weitergegeben.
Weisen Sie ticketing_stop_id für jeden Betreiber zu, der dieselbe Haltestelle im Feed verwendet.	Wenn im statischen Feed mehrere Betreiber, bei denen Fahrkarten gekauft werden können, dieselbe Haltestelle nutzen, muss die Zuweisung für jeden der Betreiber erfolgen. Weitere Informationen finden Sie im Abschnitt Felddefinitionen für ticketing_identifiers.txt.
Verwenden Sie Android-App-Links, wenn ein Deeplink zu einer Android-App erforderlich ist.	Wenn der Partner möchte, dass eine Android-App über einen Deeplink geöffnet wird, müssen Sie den Deeplink als Android-App-Link einrichten. Hinweis: Soll nur eine für Mobilgeräte optimierte Website geöffnet werden, verwenden Sie einfach die Website-URL.
Verwenden Sie universelle iOS-Links, wenn ein Deeplink zu einer iOS-App erforderlich ist.	Wenn der Partner möchte, dass eine iOS-App über einen Deeplink geöffnet wird, richten Sie den Deeplink als universellen iOS-Link ein.