Google 大眾運輸售票功能的延伸內容

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

需求條件

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

其他欄位類型

本節列出了其他欄位類型,以及含有 Google 延伸內容的欄位類型。

檔案延伸或附加內容

檔案名稱 狀態 定義
agency.txt 延伸 新增 agency.ticketing_deep_link_id
routes.txt 延伸 新增 routes.ticketing_deep_link_id
trips.txt 延伸 新增 trips.trip_ticketing_idtrips.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,可以重複。

trip_id 的候補項目。

ticketing_type 選用

(列舉) 定義透過深層連結取得售票功能是否適用於這個行程:

  • 0empty:假設為:
    • 如果在路線或運輸公司中定義了 ticketing_deep_link_id 就可以使用,
    • 否則無法使用。
  • 1:無法使用。

stop_times.txt (延伸檔案)

欄位名稱 存在必要性 詳細資料
ticketing_type 選用

(列舉) 定義透過深層連結取得售票功能是否適用於這個行程。如已定義,請覆寫 trip.ticketing_type 中設定的值。

  • 空白:如 trip.ticketing_type 所定義。
  • 0:假設為:
    • 如果在路徑或運輸公司中定義了 ticketing_deep_link_id 就可以使用,
    • 否則無法使用。

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 會使用下列參數呼叫先前的網址:

欄位名稱 存在必要性 詳細資料
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 陣列的格式。

範例

如果路段符合以下條件:

  • 在服務日 (2019 年 7 月 16 日),行程售票 ID ti1 (從停靠時間售票 ID 11 到停靠時間售票 ID 12) 的上車時間為世界標準時間下午 2 點
  • 在服務日 (2019 年 7 月 16 日),行程售票 ID ti2 (從停靠時間售票 ID 21 到停靠時間售票 ID 22) 的上車時間為世界標準時間下午 3 點

web_url 為:http://myawesomebookingwebsite.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"]

最終 URI (編碼後) 則為:

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

各種 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_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

如果要求是在 2019 年 7 月 19 日提出,且 GTFS 時間以 UTC+1 時區為準,網路呼叫就是:

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