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.ticketing_trip_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 で上書き可能です。

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: 利用不可

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 による翻訳に対応していません。
android_intent_uri 任意

（URI）android.intent.action.VIEW インテントでネイティブ Android アプリに受け渡す URI です。

空の場合は、ネイティブ Android アプリへのディープリンクを行えません。

Android におけるディープリンクについて詳しくは、アプリ コンテンツ用のディープリンクを作成するをご覧ください。

このフィールドは translations.txt による翻訳に対応していません。
ios_universal_link_url 任意

（URL）iOS で呼び出すユニバーサル リンク URL です。

空の場合、iOS でディープリンクが表示されません。

詳しくは、iOS のユニバーサル リンクについての情報をご覧ください。

このフィールドは translations.txt による翻訳に対応していません。

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。

  • 上記の値を使用できない場合、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

このフィールドは 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

このフィールドは 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

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

ガイドライン
可能な場合には、事業者または経路の間でディープリンクを共有します。

静的フィードでは、複数の事業者または経路に同じディープリンク URL がある場合は、ticketing_deep_link_id フィールドで 1 つの値を共有する必要があります。これにより、事業者または経路間の乗り換えが可能になります。
ticketing_type に一貫した値を設定します。

特定の停留所・標柱の ticketing_type 値は、stop_times.txt ファイル内のすべての行で一貫している必要があります。
親と子の両方の停留所・標柱の ticketing_stop_id をマッピングします。 乗車券販売が必要なすべての親と子の停留所・標柱に対してマッピングを行います。ticketing_identifiers.txt ファイルでは、ticketing_stop_id 値は停留所・標柱の親と子の間で伝播されません。
フィードで、同じ停留所・標柱を使用している事業者ごとに ticketing_stop_id をマッピングします。

静的フィードで、乗車券販売を有効にしている複数の事業者が同じ停留所・標柱を共有している場合は、事業者ごとにマッピングを行う必要があります。

詳しくは、ticketing_identifiers.txt のフィールドの定義セクションをご覧ください。
Android アプリへのディープリンクが必要な場合は Android アプリリンクを使用します。

パートナーがディープリンクから Android アプリを開くことを希望する場合は、ディープリンクを Android アプリリンクとしてセットアップします。
iOS アプリへのディープリンクが必要な場合は、iOS ユニバーサル リンクを使用します。 パートナーがディープリンクから iOS アプリを開くことを希望する場合は、ディープリンクを iOS ユニバーサル リンクとしてセットアップします。