本頁將介紹一部分的 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.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 |
選用 |
(來自 |
routes.txt
(延伸檔案)
欄位名稱 | 存在必要性 | 詳細資料 |
---|---|---|
ticketing_deep_link_id |
選用 | (來自 ticketing_deep_links.txt 的 ID) 定義這條路線要使用的深層連結。如有這個欄位,則會覆寫 agency.txt 中的欄位。 |
trips.txt
(延伸檔案)
欄位名稱 | 存在必要性 | 詳細資料 |
---|---|---|
ticketing_trip_id |
選用 |
(ID) 要在深層連結中傳遞的 ID,可以重複。 如果 |
ticketing_type |
選用 |
(列舉) 定義這個行程是否可透過深層連結提供票務:
|
stop_times.txt
(延伸檔案)
欄位名稱 | 存在必要性 | 詳細資料 |
---|---|---|
ticketing_type |
選用 |
(列舉) 定義這個停靠時間是否可透過深層連結提供票務。如果您定義
|
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 |
選用 |
(網址) 深層連結的到達網址。 這個欄位無法透過 |
android_intent_uri |
選用 |
(URI) 要傳遞至意圖為 如果空白,就表示無法建立原生 Android 應用程式的深層連結。 如要進一步瞭解 Android 深層連結,請參閱「建立應用程式內容的深層連結」一文。 這個欄位無法透過 |
ios_universal_link_url |
選用 |
(網址) 要在 iOS 上叫用的通用連結網址。 如果空白,iOS 上就不會顯示深層連結。 詳情請參閱「iOS 通用連結」一文。 這個欄位無法透過 |
API 呼叫中的欄位預留位置
Google 會使用下列參數呼叫 ticketing_deep_links.txt
中定義的網址:
欄位名稱 | 詳細資料 |
---|---|
service_date |
(日期,可重複) 行程的服務日。 使用此欄位做為行程從第一站出發的日期。 這個欄位會採用 JSON 陣列的格式。 |
ticketing_trip_id |
(來自 這個欄位會採用 JSON 陣列的格式。 |
from_ticketing_stop_time_id |
(可重複) 路段起點 特定停靠時間的值如下:
這個欄位會採用 JSON 陣列的格式。 |
|
(可重複) 路段終點 請參閱 這個欄位會採用 JSON 陣列的格式。 |
boarding_time |
(ISO 8601,可重複) 路段起點 使用此欄位做為乘客上車的實際日期和時間。 這個欄位的時間值符合 ISO 8601,且採用以下字串格式:
下列所有時間均相同,但所在時區不同:
這個欄位會採用 JSON 陣列的格式。 |
arrival_time |
(ISO 8601,可重複) 路段終點 stop_time 的抵達時間 (arrival_time)。 這個欄位的時間值符合 ISO 8601,且採用以下字串格式:
下列所有時間均相同,但所在時區不同:
這個欄位會採用 JSON 陣列的格式。 |
範例
在本例中,乘客旅程的路段如下:
- 在服務日
20190716
當天,行程票務 IDti1
從停靠時間票務 ID11
開始,到停靠時間票務 ID12
結束。乘客在世界標準時間下午 2 點上車,並於世界標準時間下午 2 點 50 分抵達。 - 在服務日
20190716
當天,行程票務 IDti2
從停靠時間票務 ID21
開始,到停靠時間票務 ID22
結束。乘客在世界標準時間下午 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 |
---|
|
routes.txt |
---|
|
trips.txt |
---|
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 |
---|
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 |
---|
si1,agency1,4924 si2,agency1,4676 |
ticketing_deep_links.txt |
---|
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_type 設定一致的值。 |
特定停靠站的 |
讓母停靠站和子停靠站的 ticketing_stop_id 彼此對應。 |
針對需要提供票務的所有母停靠站和子停靠站進行對應。在 ticketing_identifiers.txt 檔案中,ticketing_stop_id 值不會在母停靠站及相關子停靠站之間傳播。 |
讓在動態饋給中使用相同停靠站的每家運輸公司的 ticketing_stop_id 彼此對應。 |
在 Static 動態饋給中,如果提供票務的多家運輸公司共用同一個停靠站,每家運輸公司都必須有對應關係。 詳情請參閱「欄位定義」一節的 |
如果需要建立 Android 應用程式的深層連結,請使用 Android 應用程式連結。 |
如果合作夥伴想透過深層連結開啟 Android 應用程式,請將深層連結設為 Android 應用程式連結。 |
如果需要建立 iOS 應用程式的深層連結,請使用 iOS 通用連結。 | 如果合作夥伴想透過深層連結開啟 iOS 應用程式,請將深層連結設為 iOS 通用連結。 |