Tiện ích bán vé của Google Transit

Trang này xác định một tập hợp con của quy cách GTFS-Ticketing, đang ở giai đoạn đề xuất trong quá trình tạo tài liệu này. Trang này cũng bao gồm một số quy định hạn chế khác 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 bổ sung

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 giá trị ở dạng URI.

  • URI: Giá trị nhận dạng tài nguyên thống nhất (URI) đủ điều kiện bao gồm cả giao thức. Mọi ký tự đặc biệt trong URI đều phải sử dụng ký tự thoát chính xác. Để biết nội dung mô tả về cách tạo giá trị URI đủ điều kiện, hãy xem bài viết Mã nhận dạng tài nguyên thống nhất (URI) RFC 3986: Cú pháp chung.

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

Các tệp văn bản có trạng thái Mở rộng 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 Addition (Bổ sung) là các tệp mới do Tiện ích bán vé của Google Transit giới thiệu. Bạn cần tạo các tệp này theo Định nghĩa trường được đưa ra sau bảng sau. Hãy nhớ đưa các tệp này vào nguồn cấp dữ liệu.

Tên tệp Tiểu bang Xác định
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.ticketing_trip_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 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 trường.

Định nghĩa trường

agency.txt (tệp 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 để sử dụng cho đại lý này. Có thể ghi đè trong routes.txt.

routes.txt (tệp 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 để sử dụng cho tuyến này. Ghi đè trường trong agency.txt (nếu có).

trips.txt (tệp 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 trong đường liên kết sâu. Không bắt buộc phải là duy nhất.

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

(Enum) Xác định xem có thể mua 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ì bạn có thể sử dụng thuộc tính này.
    • Nếu không, bạn sẽ không thể sử dụng.
  • 1: Không có sẵn.

stop_times.txt (tệp 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 có thể mua vé thông qua đường liên kết sâu cho thời gian dừng này hay không. Nếu bạn xác định stop_times.ticketing_type, thì giá trị này sẽ ghi đè giá trị được đặ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ì bạn có thể sử dụng thuộc tính này.
    • Nếu không, bạn sẽ không thể sử dụng.
  • 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 giá trị nhận dạng để xử lý việc thanh toán. Các công ty vận tải có thể sử dụng cùng một giá trị nhận dạng cho một điểm dừng nhất định. Khi nhiều công ty quảng cáo 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 công ty quảng cáo.

Tên trường Sự hiện diện Thông tin chi tiết
ticketing_stop_id Bắt buộc (Mã nhận dạng) Xác định mã vé mặc định cho điểm dừng này cho công ty vận tải 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) Công ty quảng cáo 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 cần truyền đến một ứng dụng Android gốc có ý định android.intent.action.VIEW.

Nếu trường này trống, tức 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 trong ứ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 đường liên kết phổ quát để gọi trên iOS.

Nếu trống, đường liên kết sâu sẽ không hiển thị 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.

Phần 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 bảo dưỡng của chuyến đi.

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

Trường này được định dạng dưới dạng 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 dưới dạng mảng JSON.
from_ticketing_stop_time_id

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

Đối với một thời gian dừng cụ thể, giá trị sẽ 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, lớp này sẽ quay lại stop_sequence.

Trường này được định dạng dưới dạng mảng JSON.
to_ticketing_stop_time_id

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

Để biết nội dung giải thích về cách lấy giá trị, hãy xem from_ticketing_stop_time_id.

Trường này được định dạng dưới dạng mảng JSON.
boarding_time

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

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

Giá trị thời gian của trường này tuân thủ tiêu chuẩn 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:26:00+01:00
  • Ở New York, Hoa Kỳ: 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 dưới dạng mảng JSON.
arrival_time

(ISO 8601, có thể lặp lại) Thời gian đến, arrival_time tại 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: 29/7/2019 18:46:00+01:00
  • Tại New York, Hoa Kỳ: 29/7/2019 13: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 dưới dạng mảng JSON.

Ví dụ

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

  • Vào ngày cung cấp dịch vụ 20190716, mã vé của chuyến đi ti1 bắt đầu từ mã vé thời gian dừng 11 đến mã vé thời gian dừng 12. Hành khách lên máy bay lúc 2:00 chiều theo giờ UTC và đến nơi lúc 2:50 chiều theo giờ UTC.
  • Vào ngày cung cấp dịch vụ 20190716, mã vé của chuyến đi ti2 bắt đầu từ mã vé thời gian dừng 21 đến mã vé thời gian dừng 22. Hành khách lên máy bay lúc 3:00 chiều theo giờ UTC và đến nơi lúc 3:50 chiều theo giờ UTC.

Trong ví dụ này, web_url là https://examplepetstore.com.

Dựa trên tất cả thông tin này, hãy sử dụng các giá trị sau cho các tham 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ã nhận dạng khác nhau cho mục đích phát hành vé bằng trường ticketing_identifiers.txt. Các giá trị in đậm là những giá trị có trong lệnh gọi 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,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

Nếu yêu cầu được thực hiện vào ngày 19/7/2019 và thời gian 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 mua 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 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 URL đường liên kết sâu, thì các đại lý hoặc tuyến đó 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.
Đặ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.
Ánh xạ ticketing_stop_id cho cả điểm dừng mẹ và con. Thực hiện việc liên kết cho tất cả các điểm dừng mẹ và con cần mua vé. Trong tệp ticketing_identifiers.txt, các giá trị ticketing_stop_id không được truyền giữa điểm dừng mẹ và các điểm dừng con.
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 công ty hỗ trợ bán vé có cùng một điểm dừng, thì bạn phải có mối liên kết cho từng công ty.

Để biết thêm thông tin, 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 một đườ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 đó làm Đường liên kết đến ứng dụng Android.
Sử dụng Đường liên kết phổ quát trên iOS khi cần đườ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 một Đường liên kết phổ quát trên iOS.