Google 大眾運輸票務擴充功能

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

需求條件

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

其他欄位類型

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

• URI：包含架構的完整統一資源識別碼 (URI)。URI 中的所有特殊字元都必須使用正確的逸出字元。如需有關如何建立完整 URI 值的說明，請參閱「RFC 3986 統一資源識別碼 (URI)：一般語法」一文。

檔案延伸或附加內容

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

狀態為「附加」的文字檔，是指 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 中覆寫。 注意：如要為整個 Static 動態饋給套用票務，請在 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) 要在深層連結中傳遞的 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	選用	(網址) 深層連結的到達網址。 這個欄位無法透過 translations.txt 翻譯。 重要事項：這個欄位不支援網址翻譯，因此語言偵測作業必須由接收的網站或應用程式執行。
android_intent_uri	選用	(URI) 要傳遞至意圖為 android.intent.action.VIEW 的原生 Android 應用程式的 URI。 如果空白，就表示無法建立原生 Android 應用程式的深層連結。 重要事項：這個欄位不支援網址翻譯，因此語言偵測作業必須由接收的網站或應用程式執行。 如要進一步瞭解 Android 深層連結，請參閱「建立應用程式內容的深層連結」一文。 建議：使用 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。 重要事項：這個欄位只會針對停靠站本身使用 ticketing_identifiers。即使該停靠站有母停靠站，我們也會略過母停靠站的 ticketing_identifiers。 否則，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

重要事項：請注意，boarding_time 和 arrival_time 中的值 (以世界標準時間為準) 不一定會採用 GTFS 中的時區 (UTC+1)，因此 HH:MM:SS 值會有變動。

建議做法

如要導入 Google 大眾運輸票務擴充功能，請遵循以下建議：

守則
盡量讓不同的運輸公司或路線使用相同的深層連結。	在 Static 動態饋給中，如果多個運輸公司或路線使用相同的深層連結網址，ticketing_deep_link_id 欄位的值則必須相同，這樣乘客就能在不同的運輸公司或路線之間轉乘。 注意：如果不這樣做，乘客就會因為 ticketing_deep_link_id 中的值不同，而必須購買兩段票。
為 ticketing_type 設定一致的值。	特定停靠站的 ticketing_type 值在 stop_times.txt 檔案的所有資料列中必須一致。 注意：如果 ticketing_type 的值為 1，使用該停靠站的所有行程就會停止提供票務。
讓母停靠站和子停靠站的 ticketing_stop_id 彼此對應。	針對需要提供票務的所有母停靠站和子停靠站進行對應。在 ticketing_identifiers.txt 檔案中，ticketing_stop_id 值不會在母停靠站及相關子停靠站之間傳播。
讓在動態饋給中使用相同停靠站的每家運輸公司的 ticketing_stop_id 彼此對應。	在 Static 動態饋給中，如果提供票務的多家運輸公司共用同一個停靠站，每家運輸公司都必須有對應關係。 詳情請參閱「欄位定義」一節的 ticketing_identifiers.txt 部分。
如果需要建立 Android 應用程式的深層連結，請使用 Android 應用程式連結。	如果合作夥伴想透過深層連結開啟 Android 應用程式，請將深層連結設為 Android 應用程式連結。 注意：如果合作夥伴只想開啟支援行動裝置的網站，請直接使用該網站的網址。
如果需要建立 iOS 應用程式的深層連結，請使用 iOS 通用連結。	如果合作夥伴想透過深層連結開啟 iOS 應用程式，請將深層連結設為 iOS 通用連結。