Google 大眾運輸票務擴充功能

本頁將介紹一部分的 GTFS 票務規格 (在這份說明文件編寫期間仍處於提案階段)，並且列出 Google 的幾項額外限制。

需求條件

stop_times.txt 中的 departure_time 欄位為必要欄位。

其他欄位類型

本節列出其他欄位類型，以及含有 Google 擴充功能的欄位類型。部分欄位需要 URI 形式的值。

檔案延伸或附加內容

狀態為「延伸」的文字檔，是指已存在且需要延伸的檔案。您必須加入我們在下表中定義的新欄位。

狀態為「附加」的文字檔，是指 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) 要在深層連結中傳遞的 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 選用

(網址) 深層連結的到達網址。

這個欄位無法透過 translations.txt 翻譯。
android_intent_uri 選用

(URI) 要傳遞至意圖為 android.intent.action.VIEW 的原生 Android 應用程式的 URI。

如果空白，就表示無法建立原生 Android 應用程式的深層連結。

如要進一步瞭解 Android 深層連結，請參閱「建立應用程式內容的深層連結」一文。

這個欄位無法透過 translations.txt 翻譯。
ios_universal_link_url 選用

(網址) 要在 iOS 上叫用的通用連結網址。

如果空白，iOS 上就不會顯示深層連結。

詳情請參閱「iOS 通用連結」一文。

這個欄位無法透過 translations.txt 翻譯。

API 呼叫中的欄位預留位置

Google 會使用下列參數呼叫 ticketing_deep_links.txt 中定義的網址：

欄位名稱 詳細資料
service_date

(日期，可重複) 行程的服務日。

使用此欄位做為行程從第一站出發的日期。

這個欄位會採用 JSON 陣列的格式。
ticketing_trip_id

(來自 trips.txt 的 ID，可重複) 行程的 ID。

這個欄位會採用 JSON 陣列的格式。
from_ticketing_stop_time_id

(可重複) 路段起點 stop_time 的 ID。

特定停靠時間的值如下：

  • 在 ticketing_identifiers.txt 中針對 stop_time 的 agency_id 和 stop_id 定義的 ticketing_stop_id。

  • 否則，就會改為採用 stop_sequence。

這個欄位會採用 JSON 陣列的格式。
to_ticketing_stop_time_id

(可重複) 路段終點 stop_time 的 ID。

請參閱 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 開始，到停靠時間票務 ID 12 結束。乘客在世界標準時間下午 2 點上車，並於世界標準時間下午 2 點 50 分抵達。
  • 在服務日 20190716 當天，行程票務 ID ti2 從停靠時間票務 ID 21 開始，到停靠時間票務 ID 22 結束。乘客在世界標準時間下午 3 點上車，並於世界標準時間下午 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 年 7 月 19 日提出，且 GTFS 時間以 UTC+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 大眾運輸票務擴充功能，請遵循以下建議：

守則
盡量讓不同的運輸公司或路線使用相同的深層連結。

在 Static 動態饋給中，如果多個運輸公司或路線使用相同的深層連結網址，ticketing_deep_link_id 欄位的值必須相同，這樣乘客就能在不同的運輸公司或路線之間轉乘。
為 ticketing_type 設定一致的值。

特定停靠站的 ticketing_type 值在 stop_times.txt 檔案的所有資料列中必須一致。
讓母停靠站和子停靠站的 ticketing_stop_id 彼此對應。 針對需要提供票務的所有母停靠站和子停靠站進行對應。在 ticketing_identifiers.txt 檔案中，ticketing_stop_id 值不會在母停靠站及相關子停靠站之間傳播。
讓在動態饋給中使用相同停靠站的每家運輸公司的 ticketing_stop_id 彼此對應。

在 Static 動態饋給中，如果提供票務的多家運輸公司共用同一個停靠站，每家運輸公司都必須有對應關係。

詳情請參閱「欄位定義」一節的 ticketing_identifiers.txt 部分。
如果需要建立 Android 應用程式的深層連結，請使用 Android 應用程式連結。

如果合作夥伴想透過深層連結開啟 Android 應用程式，請將深層連結設為 Android 應用程式連結。
如果需要建立 iOS 應用程式的深層連結，請使用 iOS 通用連結。 如果合作夥伴想透過深層連結開啟 iOS 應用程式，請將深層連結設為 iOS 通用連結。