Tiện ích bán vé Google Transit

Trang này xác định một phần quy cách bán vé GTFS, nằm trong giai đoạn đề xuất trong quá trình tạo tài liệu này. Trang này cũng đặt ra một số quy định hạn chế bổ sung của Google.

Yêu cầu

Trường departure_time trong stop_times.txt là cần thiết.

Các loại trường khác

Phần này trình bày các loại trường bổ sung và các loại trường có phần mở rộng của Google. Một số trường yêu cầu các giá trị dưới dạng URI.

Đuôi tệp hoặc phần bổ sung

Các tệp văn bản có trạng thái Tiện ích là các tệp đã tồn tại và bạn cần mở rộng. Bạn phải thêm các trường mới mà chúng tôi xác định trong bảng sau.

Các tệp văn bản có trạng thái Thêm là các tệp mới được Tiện ích bán vé của Google Transit. Bạn cần tạo các tệp này theo Định nghĩa các trường được nêu sau bảng sau. Hãy nhớ đưa những tệp này vào nguồn cấp dữ liệu của bạn.

Tên tệp Tiểu bang Định nghĩa
agency.txt Phần mở rộng Thêm agency.ticketing_deep_link_id.
routes.txt Phần mở rộng Thêm routes.ticketing_deep_link_id.
trips.txt Phần mở rộng Thêm trips.trip_ticketing_id và trips.ticketing_type.
stop_times.txt Phần mở rộng Thêm stop_times.ticketing_type.
ticketing_identifiers.txt Phép cộng Tệp mới. Để biết thêm thông tin chi tiết, hãy xem phần Định nghĩa các trường.
ticketing_deep_links.txt Phép cộng Tệp mới. Để biết thêm thông tin chi tiết, hãy xem phần Định nghĩa các trường.

Định nghĩa trường

agency.txt (tệp được mở rộng)

Tên trường Sự hiện diện Thông tin chi tiết
ticketing_deep_link_id Không bắt buộc

(Mã nhận dạng từ ticketing_deep_links.txt) Xác định đường liên kết sâu cần sử dụng cho công ty quảng cáo này. Có thể ghi đè sau routes.txt.

routes.txt (tệp được mở rộng)

Tên trường Sự hiện diện Thông tin chi tiết
ticketing_deep_link_id Không bắt buộc (Mã nhận dạng từ ticketing_deep_links.txt) Xác định đường liên kết sâu cần sử dụng cho tuyến này. Nếu có, hãy ghi đè trường trong agency.txt.

trips.txt (tệp được mở rộng)

Tên trường Sự hiện diện Thông tin chi tiết
ticketing_trip_id Không bắt buộc

(Mã nhận dạng) Giá trị nhận dạng để truyền vào đường liên kết sâu. Không nhất thiết phải là duy nhất.

Nếu ticketing_trip_id trống, hệ thống sẽ sử dụng giá trị trip_id.
ticketing_type Không bắt buộc

(Enum) Xác định xem bạn có thể sử dụng tính năng bán vé thông qua đường liên kết sâu cho chuyến đi này hay không:

  • 0 hoặc trống:
    • Nếu bạn xác định ticketing_deep_link_id cho tuyến hoặc đại lý, thì thuộc tính này có sẵn.
    • Không có sẵn.
  • 1: Không có sẵn.

stop_times.txt (tệp được mở rộng)

Tên trường Sự hiện diện Thông tin chi tiết
ticketing_type Không bắt buộc

(Enum) Xác định xem tính năng bán vé thông qua đường liên kết sâu có dùng được cho thời gian dừng này hay không. Nếu bạn xác định stop_times.ticketing_type, thao tác này sẽ ghi đè giá trị đã đặt trong trip.ticketing_type.

  • Trống: Sử dụng giá trị từ trip.ticketing_type.
  • 0:
    • Nếu bạn xác định ticketing_deep_link_id cho tuyến hoặc đại lý, thì thuộc tính này có sẵn.
    • Không có sẵn.
  • 1: Không có sẵn.

ticketing_identifiers.txt (đã thêm tệp)

Trường hợp phổ biến nhất đối với việc bán vé là mỗi điểm dừng đều có một mã nhận dạng để xử lý thông tin thanh toán. Các đại lý khác nhau có thể sử dụng cùng một giá trị nhận dạng cho một điểm dừng cụ thể. Khi nhiều đại lý phân phát cùng một điểm dừng, hãy lặp lại mối liên kết này cho từng đại lý.

Tên trường Sự hiện diện Thông tin chi tiết
ticketing_stop_id Bắt buộc (Mã) Xác định mã bán vé mặc định cho điểm dừng này của công ty quảng cáo này.
stop_id Bắt buộc (Mã nhận dạng từ stops.txt) Điểm dừng mà ticketing_stop_id mặc định được xác định.
agency_id Bắt buộc (Mã nhận dạng từ agency.txt) Đại lý của điểm dừng mà ticketing_stop_id mặc định được xác định.

ticketing_deep_links.txt (đã thêm tệp)

Tên trường Sự hiện diện Thông tin chi tiết
ticketing_deep_link_id Bắt buộc (Mã nhận dạng) Xác định mã nhận dạng cho đường liên kết sâu.
web_url Không bắt buộc

(URL) URL cần truy cập để liên kết sâu.

Không thể dịch trường này thông qua translations.txt.
android_intent_uri Không bắt buộc

(URI) URI để chuyển đến ứng dụng Android gốc có ý định android.intent.action.VIEW.

Nếu trống, điều đó có nghĩa là bạn không thể liên kết sâu đến một ứng dụng Android gốc.

Để biết thêm thông tin về đường liên kết sâu trên Android, hãy xem bài viết Tạo đường liên kết sâu đến nội dung ứng dụng.

Không thể dịch trường này thông qua translations.txt.
ios_universal_link_url Không bắt buộc

(URL) URL liên kết chung để gọi trên iOS.

Nếu trống, đường liên kết sâu sẽ không xuất hiện trên iOS.

Để biết thêm thông tin, hãy xem bài viết Đường liên kết phổ quát trên iOS.

Không thể dịch trường này thông qua translations.txt.

Trình giữ chỗ trường trong lệnh gọi API

Google gọi các URL được xác định trong ticketing_deep_links.txt bằng các tham số sau:

Tên trường Thông tin chi tiết
service_date

(Ngày, có thể lặp lại) Ngày phục vụ của chuyến đi.

Hãy sử dụng trường này cho ngày mà chuyến đi khởi hành từ điểm dừng đầu tiên.

Trường này có định dạng là một mảng JSON.
ticketing_trip_id

(Mã nhận dạng từ trips.txt, có thể lặp lại) Giá trị nhận dạng của chuyến đi.

Trường này có định dạng là một mảng JSON.
from_ticketing_stop_time_id

(Có thể lặp lại) Giá trị nhận dạng của stop_time khi chân bắt đầu.

Đối với một thời gian ngừng cụ thể, giá trị như sau:

  • ticketing_stop_id được xác định trong ticketing_identifiers.txt cho agency_id và stop_id của stop_time.

  • Nếu không, mô-đun này sẽ quay lại trên stop_sequence.

Trường này có định dạng là một mảng JSON.
to_ticketing_stop_time_id

(Có thể lặp lại) Giá trị nhận dạng của stop_time mà chân kết thúc.

Để biết nội dung giải thích về quá trình dẫn xuất giá trị, hãy xem from_ticketing_stop_time_id.

Trường này có định dạng là một mảng JSON.
boarding_time

(ISO 8601, có thể lặp lại) Thời gian khởi hành, departure_time, của stop_time nơi bắt đầu chặng bay.

Hãy sử dụng trường này cho ngày và giờ thực tế khi hành khách lên xe.

Giá trị thời gian của trường này tuân thủ ISO 8601 với định dạng chuỗi như sau:

YYYY-MM-DDThh:mm:ss±hh:mm

Tất cả thời gian dưới đây đều giống nhau, ở các múi giờ khác nhau:

  • Tại London, Vương quốc Anh: 2019-07-29T18:26:00+01:00
  • Ở thành phố New York, Hoa Kỳ – New York: 2019-07-29T13:26:00-04:00
  • Tại Tokyo, Nhật Bản: 2019-07-30T02:26:00+09:00

Trường này có định dạng là một mảng JSON.
arrival_time

(ISO 8601, repeatable) Thời gian đến, thời gian đến tại thời điểm Stop_time mà chặng kết thúc.

Giá trị thời gian của trường này tuân thủ ISO 8601 với định dạng chuỗi sau:

YYYY-MM-DDThh:mm:ss±,hh:mm

Tất cả thời gian dưới đây đều giống nhau, ở các múi giờ khác nhau:

  • Tại London, Vương quốc Anh: 2019-07-29T18:46:00+01:00
  • Tại NYC, Hoa Kỳ-NY: 2019-07-29T13:46:00-04:00
  • Tại Tokyo, Nhật Bản: 2019-07-30T02:46:00+09:00

Trường này có định dạng là một mảng JSON.

Ví dụ

Trong ví dụ này, sau đây là các chân trong hành trình của một hành khách:

  • Vào ngày sử dụng dịch vụ 20190716, mã bán vé cho chuyến đi ti1 bắt đầu từ mã bán vé tại thời điểm ngừng hoạt động 11 đến mã bán vé cho thời gian ngừng hoạt động 12. Lên tàu lúc 2:00 chiều (giờ UTC) và đến lúc 2:50 chiều (giờ UTC).
  • Vào ngày sử dụng dịch vụ 20190716, mã bán vé cho chuyến đi ti2 bắt đầu từ mã bán vé tại thời điểm ngừng hoạt động 21 đến mã bán vé cho thời gian ngừng hoạt động 22. Các chuyến xe hành khách lên máy bay lúc 3:00 chiều (giờ UTC) và đến lúc 3:50 chiều (giờ UTC).

Đối với ví dụ này, web_url là https://examplepetstore.com.

Với tất cả thông tin này, hãy sử dụng các giá trị sau cho thông số của nguồn cấp dữ liệu cho chuyến đi này:

Tên trường Thông tin chi tiết
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"]

Sau đây là URI cuối cùng sau khi mã hoá:

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

Ví dụ về các giá trị ticketing_stop_id khác nhau

Các điểm dừng có thể có mã khác nhau cho mục đích bán vé bằng trường ticketing_identifiers.txt. Các giá trị in đậm là những giá trị tìm thấy trong lệnh gọi trên web được mô tả sau các tệp.

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,mỗi ngày,ri1,"TGV INOUI 6603",FR_SNCF_6603

ti2,mỗi ngày,ri1,"TGV INOUI 6681",FR_SNCF_6681

ti3,mỗi ngày,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

Nếu yêu cầu được đưa ra vào ngày 19/7/2019 và thời gian của GTFS theo múi giờ UTC+1, thì sau đây là lệnh gọi cho web:

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

Hãy làm theo các đề xuất sau để triển khai tiện ích bán vé của Google Transit:

Nguyên tắc
Chia sẻ đường liên kết sâu giữa các đại lý hoặc tuyến đường bất cứ khi nào có thể.

Trong nguồn cấp dữ liệu tĩnh, bất cứ khi nào nhiều đại lý hoặc tuyến có cùng một URL liên kết sâu, họ phải chia sẻ một giá trị duy nhất cho trường ticketing_deep_link_id. Điều này cho phép chuyển giữa các đại lý hoặc tuyến đường.
Đặt giá trị nhất quán cho ticketing_type.

Giá trị ticketing_type cho một điểm dừng cụ thể phải nhất quán trên tất cả các hàng trong tệp stop_times.txt.
Lập bản đồ ticketing_stop_id cho cả trạm dừng chính và trạm con. Thực hiện liên kết cho tất cả điểm dừng chính và điểm dừng con yêu cầu bán vé. Trong tệp ticketing_identifiers.txt, các giá trị ticketing_stop_id không truyền giữa điểm dừng mẹ và điểm dừng con của nó.
Liên kết ticketing_stop_id cho từng công ty quảng cáo sử dụng cùng một điểm dừng trong nguồn cấp dữ liệu.

Trong nguồn cấp dữ liệu tĩnh, nếu nhiều đại lý bật tính năng bán vé có cùng một điểm dừng, thì từng đại lý phải có mối liên kết này.

Để biết thêm thông tin chi tiết, hãy tham khảo phần Định nghĩa trường cho ticketing_identifiers.txt.
Sử dụng Đường liên kết trong ứng dụng Android khi cần phải có đường liên kết sâu đến ứng dụng Android.

Nếu đối tác muốn mở một ứng dụng Android từ một đường liên kết sâu, hãy thiết lập đường liên kết sâu đó dưới dạng Đường liên kết trong ứng dụng Android.
Sử dụng Đường liên kết phổ quát trên iOS khi cần phải có đường liên kết sâu đến ứng dụng iOS. Nếu đối tác muốn mở một ứng dụng iOS từ một đường liên kết sâu, hãy thiết lập đường liên kết sâu dưới dạng Đường liên kết phổ quát iOS.