Google 乗換案内の乗車券販売の拡張機能

このページでは、本ドキュメントの作成時点では提案段階にある GTFS-Ticketing 仕様のサブセットを定義します。また、Google による追加の制限もいくつか記載されています。

要件

stop_times.txt の departure_time フィールドは必須です。

追加のフィールド タイプ

このセクションでは、追加のフィールド タイプと、Google による拡張を含むフィールド タイプについて概説します。一部のフィールドでは、URI 形式の値が必要です。

• URI: スキームを含む完全修飾 Uniform Resource Identifier（URI）。URI に特殊文字が含まれる場合、すべて適切にエスケープする必要があります。完全修飾 URI を作成する方法については、RFC 3986 Uniform Resource Identifier (URI): Generic Syntax をご覧ください。

ファイルの拡張 / 追加

ステータスが「拡張」のテキスト ファイルは、拡張が必要な既存のファイルです。次の表で定義されている新しいフィールドを追加する必要があります。

ステータスが「追加」のテキスト ファイルは、Google 乗換案内の乗車券販売の拡張機能によって導入された新しいファイルです。これらのファイルは、次の表に示すフィールド定義に従って作成する必要があります。これらのファイルは必ずフィードに含めてください。

ファイル名	状態	定義内容
agency.txt	拡張	agency.ticketing_deep_link_id を追加します。
routes.txt	拡張	routes.ticketing_deep_link_id を追加します。
trips.txt	拡張	trips.trip_ticketing_id と trips.ticketing_type を追加します。
stop_times.txt	拡張	stop_times.ticketing_type を追加します。
ticketing_identifiers.txt	追加	新しいファイルです。詳細については、フィールドの定義をご覧ください。
ticketing_deep_links.txt	追加	新しいファイルです。詳細については、フィールドの定義をご覧ください。

フィールドの定義

agency.txt（拡張されたファイル）

フィールド名	必須かどうか	詳細
ticketing_deep_link_id	任意	（ticketing_deep_links.txt 由来の ID）該当事業者に対して使用するディープリンクを定義します。routes.txt で上書き可能です。 注: 静的フィード全体に乗車券販売を適用するには、agency.txt ファイルのすべての事業者の ticketing_deep_link_id フィールドに同じ値を設定します。

routes.txt（拡張されたファイル）

フィールド名	必須かどうか	詳細
ticketing_deep_link_id	任意	（ticketing_deep_links.txt 由来の ID）該当経路に対して使用するディープリンクを定義します。このフィールドを追加した場合は、agency.txt のフィールドが上書きされます。

trips.txt（拡張されたファイル）

フィールド名	必須かどうか	詳細
ticketing_trip_id	任意	（ID）ディープリンクで受け渡す識別子です。一意である必要はありません。 ticketing_trip_id が空の場合、代わりに trip_id の値が使用されます。
ticketing_type	任意	（列挙型）該当の便に対して、ディープリンクによる乗車券販売が利用可能かどうかを次のように定義します。 0 または空: 経路または事業者に ticketing_deep_link_id を定義している場合は、ディープリンクによる乗車券販売が利用可能となります。 それ以外の場合は利用不可となります。 1: 利用不可

stop_times.txt（拡張されたファイル）

フィールド名	必須かどうか	詳細
ticketing_type	任意	（列挙型）該当の通過時刻に対して、ディープリンクによる乗車券販売が利用可能かどうかを次のように定義します。stop_times.ticketing_type を定義すると、trip.ticketing_type に設定された値がオーバーライドされます。 空: trip.ticketing_type の値が使用されます。 0: 経路または事業者に ticketing_deep_link_id を定義している場合は、ディープリンクによる乗車券販売が利用可能となります。 それ以外の場合は利用不可となります。 1: 利用不可 重要: ある stop_id について、対応する stop_times の中に ticketing_type=1 を持つものがひとつでもある場合、他の stop_times もすべて ticketing_type=1 を持つ必要があります。

ticketing_identifiers.txt（ファイル追加）

乗車券販売において最も一般的なのは、駅 / 停留所にそれぞれ請求処理用の ID が割り当てられているケースです。事業者が異なれば、任意の駅 / 停留所に同一 ID が割り当てられることもあります。同じ駅 / 停留所に複数の事業者が乗り入れている場合、事業者ごとにこのマッピングを繰り返してください。

フィールド名	必須かどうか	詳細
ticketing_stop_id	必須	（ID）該当事業者の該当する停留所・標柱に対して、デフォルトの乗車券販売 ID を定義します。
stop_id	必須	（stops.txt 由来の ID）デフォルトの ticketing_stop_id が定義された駅 / 停留所です。
agency_id	必須	（agency.txt 由来の ID）デフォルトの ticketing_stop_id が定義された駅 / 停留所の事業者です。

ticketing_deep_links.txt（ファイル追加）

フィールド名	必須かどうか	詳細
ticketing_deep_link_id	必須	（ID）ディープリンクの ID を定義します。
web_url	任意	（URL）ディープリンク用のアクセス先 URL です。 このフィールドは translations.txt による翻訳に対応していません。 重要: このフィールドには URL 翻訳がサポートされないため、言語の検出は受け取り側のウェブサイトまたはアプリで行う必要があります。
android_intent_uri	任意	（URI）android.intent.action.VIEW インテントでネイティブ Android アプリに受け渡す URI です。 空の場合は、ネイティブ Android アプリへのディープリンクを行えません。 重要: このフィールドには URL 翻訳がサポートされないため、言語の検出は受け取り側のウェブサイトまたはアプリで行う必要があります。 Android におけるディープリンクについて詳しくは、アプリ コンテンツ用のディープリンクを作成するをご覧ください。 推奨事項: Android アプリリンクを使用することをおすすめします。セキュリティにおいても、乗客のデバイスにネイティブ Android アプリがインストールされていない場合のフォールバック動作においても優れています。 このフィールドは translations.txt による翻訳に対応していません。
ios_universal_link_url	任意	（URL）iOS で呼び出すユニバーサル リンク URL です。 重要: このフィールドには URL 翻訳がサポートされないため、言語の検出は受け取り側のウェブサイトまたはアプリで行う必要があります。 空の場合、iOS でディープリンクが表示されません。 詳しくは、iOS のユニバーサル リンクについての情報をご覧ください。 このフィールドは translations.txt による翻訳に対応していません。

注: 複数の事業者または経路がフィードで同じディープリンク URL を共有している場合、ディープリンクは 1 つだけ定義し、該当事業者または経路をすべて同じディープリンクにリンクすることを強くおすすめします。詳しくは、おすすめの実装方法のセクションをご覧ください。

API 呼び出し内のフィールド プレースホルダ

ticketing_deep_links.txt で定義された URL が次のパラメータ付きで呼び出されます。

フィールド名	詳細
service_date	（日付、反復可能）便の運行日です。 このフィールドは JSON 配列形式です。
ticketing_trip_id	（trips.txt 由来の ID、反復可能）便の識別子です。 このフィールドは JSON 配列形式です。
from_ticketing_stop_time_id	（反復可能）区間の始点の stop_time の識別子です。 各通過時刻について、値は次のようになります。 stop_time の agency_id と stop_id に対して ticketing_identifiers.txt で定義された ticketing_stop_id。 重要: ここで使用されるのは該当の停留所・標柱自体の ticketing_identifiers のみです。該当の停留所・標柱の親にあたる停留所・標柱が存在する場合も、親側の ticketing_identifiers は無視されます。 上記の値を使用できない場合、stop_sequence にフォールバックします。 このフィールドは JSON 配列形式です。
to_ticketing_stop_time_id	（反復可能）区間の終点の stop_time の識別子です。 値の導出方法については from_ticketing_stop_time_id をご覧ください。 このフィールドは JSON 配列形式です。
boarding_time	（ISO 8601、反復可能）区間の始点の stop_time の出発時刻（departure_time）です。 このフィールドの時刻値は ISO 8601 準拠で、フォーマット文字列は次のようになります。 YYYY-MM-DDThh:mm:ss±hh:mm 以下はすべて同一の時刻です（各タイムゾーンに準じた形式で記述したもの）。 ロンドン（英国）: 2019-07-29T18:26:00+01:00 ニューヨーク市（米国ニューヨーク州）: 2019-07-29T13:26:00-04:00 東京（日本）: 2019-07-30T02:26:00+09:00 重要: タイムゾーンはフィードに含まれる事業者のタイムゾーンと必ずしも同じではありません。タイムゾーンは UTC ベースです。 このフィールドは JSON 配列形式です。
arrival_time	（ISO 8601、反復可能）区間の終点の stop_time の到着時刻（arrival_time）です。 このフィールドの時刻値は ISO 8601 準拠で、文字列フォーマットは次のようになります。 YYYY-MM-DDThh:mm:ss±,hh:mm 以下はすべて同一の時刻です（各タイムゾーンに準じた形式で記述したもの）。 ロンドン（英国）: 2019-07-29T18:46:00+01:00 ニューヨーク市（米国ニューヨーク州）: 2019-07-29T13:46:00-04:00 東京（日本）: 2019-07-30T02:46:00+09:00 重要: タイムゾーンは、フィードに含まれる事業者のタイムゾーンと必ずしも同じではありません。タイムゾーンは UTC ベースです。 このフィールドは JSON 配列形式です。

例

この例では、乗客の行程の区間は次のとおりです。

• 運行日 20190716、便の乗車券販売 ID「ti1」、通過時刻の乗車券販売 ID「11」～「12」。乗客は UTC 午後 2 時に乗車し、UTC 午後 2 時 50 分に到着します。
• 運行日 20190716、便の乗車券販売 ID「ti2」、通過時刻の乗車券販売 ID「21」～「22」。乗客は UTC 午後 3 時に乗車し、UTC 午後 3 時 50 分に到着します。

この例では、web_url は https://examplepetstore.com です。

上記のすべての情報を定義するには、この便のフィードのパラメータに次の値を使用します。

フィールド名	詳細
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"]

エンコード後の最終的な URI は次のようになります。

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

異なる ticketing_stop_id 値の例

停留所・標柱には、ticketing_identifiers.txt のフィールドを使って、乗車券販売の目的ごとに異なる ID を指定できます。太字になっている箇所が、各ファイルの後に記載するウェブ呼び出しに含まれる値です。

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

リクエスト日が 2019-07-19 で、GTFS 時刻のタイムゾーンが UTF+1 の場合、ウェブ呼び出しは次のようになります。

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

重要: boarding_time と arrival_time 内の値のタイムゾーン（UTF）は GTFS のタイムゾーン（UTC+1）と必ずしも一致しないため、HH:MM:SS 値がずれる場合があります。

おすすめの実装方法

以下の推奨事項に沿って、Google 乗換案内の乗車券販売の拡張機能を実装してください。

ガイドライン
可能な場合には、事業者または経路の間でディープリンクを共有します。	静的フィードでは、複数の事業者または経路に同じディープリンク URL がある場合は、ticketing_deep_link_id フィールドで 1 つの値を共有する必要があります。これにより、事業者または経路間の乗り換えが可能になります。 注: 共有していない場合は、ticketing_deep_link_id の値が異なるため、乗客は乗車券を 2 枚購入する必要が生じます。
ticketing_type に一貫した値を設定します。	特定の停留所・標柱の ticketing_type 値は、stop_times.txt ファイル内のすべての行で一貫している必要があります。 注: ticketing_type 値を 1 にすると、その停留所・標柱を使用するすべての便の乗車券販売が無効になります。
親と子の両方の停留所・標柱の ticketing_stop_id をマッピングします。	乗車券販売が必要なすべての親と子の停留所・標柱に対してマッピングを行います。ticketing_identifiers.txt ファイルでは、ticketing_stop_id 値は停留所・標柱の親と子の間で伝播されません。
フィードで、同じ停留所・標柱を使用している事業者ごとに ticketing_stop_id をマッピングします。	静的フィードで、乗車券販売を有効にしている複数の事業者が同じ停留所・標柱を共有している場合は、事業者ごとにマッピングを行う必要があります。 詳しくは、ticketing_identifiers.txt のフィールドの定義セクションをご覧ください。
Android アプリへのディープリンクが必要な場合は Android アプリリンクを使用します。	パートナーがディープリンクから Android アプリを開くことを希望する場合は、ディープリンクを Android アプリリンクとしてセットアップします。 注: パートナーがモバイル対応ウェブサイトのみを開くことを希望する場合は、ウェブサイトの URL を直接使用します。
iOS アプリへのディープリンクが必要な場合は、iOS ユニバーサル リンクを使用します。	パートナーがディープリンクから iOS アプリを開くことを希望する場合は、ディープリンクを iOS ユニバーサル リンクとしてセットアップします。