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

Trang này xác định một phần trong quy cách Bán vé của GTFS, đang trong 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ó tiện ích của Google. Hơi nhiều các trường yêu cầu các giá trị dưới dạng URI.

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

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

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 về 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 về trường.

Định nghĩa các 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ã từ ticketing_deep_links.txt) Xác định đường liên kết sâu cần sử dụng cho lượt chuyển đổi này đại lý. 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ã từ ticketing_deep_links.txt) Xác định đường liên kết sâu cần sử dụng cho lượt chuyển đổi này tuyến đường. Nếu có, hãy ghi đè trường trong agency.txt.

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 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ị của Hãy trip_id.
ticketing_type Không bắt buộc

(Enum) Xác định xem chuyến đi này có hỗ trợ tính năng bán vé qua đường liên kết sâu hay không:

  • 0 hoặc trống:
    • Nếu bạn xác định ticketing_deep_link_id cho tuyến đường hoặc đại lý, thì đây là sẵn có.
    • Nếu không thì không dùng được.
  • 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ó tính năng bán vé 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, 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 đường hoặc đại lý, thì đây là sẵn có.
    • Nếu không thì không dùng được.
  • 1: Không có sẵn.

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

Trường hợp phổ biến nhất khi bán vé là mỗi điểm dừng đều có một giá trị 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 bất kỳ điểm dừng nào. Khi nhiều đại lý phân phát tại cùng một điểm dừng, hãy lặp lại quy trình lập bản đồ này cho mỗi đạ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ã nhận dạng) 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ã từ stops.txt) Điểm dừng mà giá trị mặc định ticketing_stop_id đã được định nghĩa.
agency_id Bắt buộc (Mã từ agency.txt) Đại lý của điểm dừng mà mặc định ticketing_stop_id đã được định nghĩa.

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.

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

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

Nếu trống thì 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ề liên kết sâu trên Android, hãy xem bài viết Tạo liên kết sâu tới nội dung ứng dụng.

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

(URL) URL đường liên kết chung cần 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 Đường liên kết phổ quát trên iOS.

Bạn không thể dịch trường này bằng 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 lệnh sau thông số:

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

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

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 định dạng dưới dạng 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 định dạng dưới dạng 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 mà chặng bắt đầu.

Đối với 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, hệ thống sẽ quay lại dùng stop_sequence.

Trường này định dạng dưới dạng 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à đoạn kết thúc.

Để có giải thích về nguồn gốc của giá trị, hãy xem from_ticketing_stop_time_id.

Trường này định dạng dưới dạng 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 chặng bắt đầu.

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 theo ISO 8601 với định dạng chuỗi sau:

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

Dưới đây là thời gian như nhau, ở các múi giờ khác nhau:

  • Tại London, Vương quốc Anh: 2019-07-29T18:26:00+01:00
  • Tại 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 định dạng dưới dạng một mảng JSON.
arrival_time

(ISO 8601, có thể lặp lại) Thời gian đến, thời gian đến tại thời gian dừng_dừng kết thúc.

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

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

Dưới đây là thời gian như 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 New York, US-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 định dạng dưới dạng một mảng JSON.

Ví dụ

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

  • Vào ngày dịch vụ 20190716, mã bán vé chuyến đi ti1 bắt đầu từ điểm dừng có mã bán vé thời gian 11 để ngừng bán vé có mã thời gian 12. Hành khách 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 dịch vụ 20190716, mã bán vé chuyến đi ti2 bắt đầu từ điểm dừng có mã bán vé thời gian 21 để ngừng bán vé có mã thời gian 22. Hành khách lên tàu lúc 3:00 chiều (giờ UTC) và đến nơi lúc 3:50 chiều (giờ UTC).

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

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

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 loại Giá trị ticketing_stop_id

Các điểm dừng có thể có mã khác nhau để bán vé thông qua Trường ticketing_identifiers.txt. Giá trị in đậm là những giá trị tìm thấy trong cuộc gọi trên web được mô tả sau 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 tại Oui Paris-Lyon",tdl1
trips.txt

trip_id,service_id,route_id,trip_short_name, ticketing_trip_id

ti1,hằng ngày,ri1;"TGV INOUI 6603",FR_SNCF_6603

ti2,hàng ngày,ri1,"TGV INOUI 6681",FR_SNCF_6681

ti3,hàng 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 thực hiện vào ngày 19/07/2019 và thời gian theo GTFS theo múi giờ UTC+1, thì sau đây là lệnh gọi dành 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 Phương tiện công cộng:

Nguyên tắc
Chia sẻ đường liên kết sâu giữa các công ty quảng cáo 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 công ty quảng cáo hoặc tuyến đường có cùng URL liên kết sâu, chúng phải chia sẻ một giá trị duy nhất cho trường ticketing_deep_link_id. Chiến dịch này cho phép chuyển giữa các đại lý hoặc tuyến.
Đặt các 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.
Liên kết ticketing_stop_id cho cả điểm dừng mẹ và điểm dừng con. Tiến hành lập bản đồ cho tất cả các điểm dừng mẹ và con cần bán vé. Trong ticketing_identifiers.txt, các giá trị ticketing_stop_id thì không truyền giữa một điểm dừng mẹ và các điểm dừng con.
Liên kết ticketing_stop_id cho mỗi đại lý 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ý cho phép bán vé có cùng một điểm dừng, phải có ánh xạ cho từng đại lý.

Để biết thêm thông tin chi tiết, hãy tham khảo mục Định nghĩa trường với giá ticketing_identifiers.txt.
Sử dụng Đường liên kết trong ứng dụng Android khi cần 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 qua 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 trong ứng dụng Android.
Hãy sử dụng Đường liên kết phổ quát của iOS khi cần có đường liên kết sâu đến một ứng dụng iOS. Nếu đối tác muốn mở một ứng dụng iOS bằng 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.