Ekstensi penjualan tiket Google Transit

Halaman ini menentukan sebagian spesifikasi Penjualan Tiket GTFS, yang berada di tahap proposal saat dokumen ini dibuat. Halaman ini juga berisi beberapa batasan tambahan dari Google.

Persyaratan

Kolom departure_time di stop_times.txt harus disediakan.

Jenis kolom tambahan

Bagian ini menguraikan jenis kolom tambahan dan jenis kolom dengan perluasan dari Google. Beberapa kolom memerlukan nilai dalam bentuk URI.

  • URI: Uniform Resource Identifier (URI) yang sepenuhnya memenuhi syarat yang berisi skema. Karakter khusus dalam URI ini harus menggunakan escape yang benar. Untuk deskripsi cara membuat nilai URI yang sepenuhnya memenuhi syarat, lihat RFC 3986 Uniform Resource Identifier (URI): Generic Syntax.

Perluasan atau penambahan file

File teks dengan status Perluasan adalah file yang sudah ada dan yang perlu Anda perluas. Anda harus menambahkan kolom baru yang kami tentukan di tabel berikut.

File teks dengan status Penambahan adalah file baru yang diterapkan oleh Ekstensi Penjualan Tiket Google Transit. Anda perlu membuat file ini sesuai dengan Definisi kolom yang diberikan di tabel berikut. Pastikan untuk menyertakan file ini di feed Anda.

Nama file Negara bagian/Provinsi Definisi
agency.txt Perluasan Menambahkan agency.ticketing_deep_link_id.
routes.txt Perluasan Menambahkan routes.ticketing_deep_link_id.
trips.txt Perluasan Menambahkan trips.ticketing_trip_id dan trips.ticketing_type.
stop_times.txt Perluasan Menambahkan stop_times.ticketing_type.
ticketing_identifiers.txt Penambahan File baru. Untuk detail selengkapnya, lihat Definisi kolom.
ticketing_deep_links.txt Penambahan File baru. Untuk detail selengkapnya, lihat Definisi kolom.

Definisi kolom

agency.txt (file yang diperluas)

Nama kolom Ketersediaan Detail
ticketing_deep_link_id Opsional

(ID dari ticketing_deep_links.txt) Menentukan deep link yang akan digunakan untuk perusahaan transportasi ini. Dapat ditimpa di routes.txt.

routes.txt (file yang diperluas)

Nama kolom Ketersediaan Detail
ticketing_deep_link_id Opsional (ID dari ticketing_deep_links.txt) Menentukan deep link yang akan digunakan untuk rute ini. Jika ada, akan menimpa kolom di agency.txt.

trips.txt (file yang diperluas)

Nama kolom Ketersediaan Detail
ticketing_trip_id Opsional

(ID) ID yang akan diteruskan dalam deep link. Tidak harus unik.

Jika ticketing_trip_id kosong, sistem akan menggunakan nilai trip_id sebagai gantinya.
ticketing_type Opsional

(Enum) Menentukan apakah penjualan tiket melalui deep link tersedia untuk perjalanan ini:

  • 0 atau kosong:
    • Jika Anda menentukan ticketing_deep_link_id untuk rute atau perusahaan transportasi umum, berarti penjualan tiket tersedia.
    • Tidak tersedia jika sebaliknya.
  • 1: Tidak tersedia.

stop_times.txt (file yang diperluas)

Nama kolom Ketersediaan Detail
ticketing_type Opsional

(Enum) Menentukan apakah penjualan tiket melalui deep link tersedia untuk waktu perhentian ini. Jika Anda menentukan stop_times.ticketing_type, nilai ini akan mengganti nilai yang ditetapkan di trip.ticketing_type.

  • Kosong: Menggunakan nilai dari trip.ticketing_type.
  • 0:
    • Jika Anda menentukan ticketing_deep_link_id untuk rute atau perusahaan transportasi umum, berarti penjualan tiket tersedia.
    • Tidak tersedia jika sebaliknya.
  • 1: Tidak tersedia.

ticketing_identifiers.txt (file yang ditambahkan)

Kasus yang paling umum untuk penjualan tiket adalah setiap perhentian memiliki ID untuk memproses penagihan. Beberapa perusahaan transportasi umum mungkin menggunakan ID yang sama untuk satu perhentian. Jika beberapa perusahaan transportasi umum melayani perhentian yang sama, ulangi pemetaan ini untuk setiap perusahaan transportasi umum tersebut.

Nama kolom Ketersediaan Detail
ticketing_stop_id Wajib (ID) Menentukan ID penjualan tiket default untuk perhentian ini untuk perusahaan transportasi umum ini.
stop_id Wajib (ID dari stops.txt) Perhentian yang diberi ticketing_stop_id default.
agency_id Wajib (ID dari agency.txt) Perusahaan transportasi umum yang perhentiannya diberi ticketing_stop_id default.

ticketing_deep_links.txt (file yang ditambahkan)

Nama kolom Ketersediaan Detail
ticketing_deep_link_id Wajib (ID) Menentukan ID untuk deep link.
web_url Opsional

(URL) URL yang akan dikunjungi untuk deep linking.

Kolom ini tidak dapat diterjemahkan melalui translations.txt.
android_intent_uri Opsional

(URI) URI yang akan diteruskan ke aplikasi Android native dengan intent android.intent.action.VIEW.

Jika kosong, berarti Anda tidak dapat melakukan deep link ke aplikasi Android native.

Untuk informasi selengkapnya tentang deep link di Android, lihat Membuat deep link ke konten aplikasi.

Kolom ini tidak dapat diterjemahkan melalui translations.txt.
ios_universal_link_url Opsional

(URL) URL link universal yang akan dipanggil di iOS.

Jika kosong, deep linking tidak akan ditampilkan di iOS.

Untuk informasi selengkapnya, lihat Link Universal di iOS.

Kolom ini tidak dapat diterjemahkan melalui translations.txt.

Placeholder kolom di panggilan API

Google memanggil URL yang ditentukan di ticketing_deep_links.txt dengan parameter berikut:

Nama kolom Detail
service_date

(Tanggal, dapat diulang) Hari layanan perjalanan.

Gunakan kolom ini untuk tanggal keberangkatan perjalanan dari perhentian pertamanya.

Kolom ini diformat sebagai array JSON.
ticketing_trip_id

(ID dari trips.txt, dapat diulang) ID perjalanan.

Kolom ini diformat sebagai array JSON.
from_ticketing_stop_time_id

(Dapat diulang) ID stop_time untuk awal segmen perjalanan.

Untuk waktu perhentian tertentu, nilainya adalah sebagai berikut:

  • ticketing_stop_id yang ditentukan di ticketing_identifiers.txt untuk agency_id dan stop_id dari stop_time.

  • Atau, nilai tersebut akan fallback ke stop_sequence.

Kolom ini diformat sebagai array JSON.
to_ticketing_stop_time_id

(Dapat diulang) ID stop_time untuk akhir segmen perjalanan.

Untuk penjelasan tentang asal nilai, lihat from_ticketing_stop_time_id.

Kolom ini diformat sebagai array JSON.
boarding_time

(ISO 8601, dapat diulang) Waktu keberangkatan, departure_time, dari stop_time untuk awal segmen perjalanan.

Gunakan kolom ini untuk tanggal dan waktu sebenarnya saat penumpang menaiki kendaraan.

Nilai waktu kolom ini mengikuti ISO 8601 dengan format string berikut:

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

Semua waktu di bawah ini sama, tetapi dalam zona waktu yang berbeda-beda:

  • Di London, Inggris Raya: 2019-07-29T18:26:00+01:00
  • Di NYC, AS-NY: 2019-07-29T13:26:00-04:00
  • Di Tokyo, Jepang: 2019-07-30T02:26:00+09:00

Kolom ini diformat sebagai array JSON.
arrival_time

(ISO 8601, dapat diulang) Waktu kedatangan, arrival_time pada stop_time untuk akhir segmen perjalanan.

Nilai waktu kolom ini mengikuti ISO 8601 dengan format string berikut:

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

Semua waktu di bawah ini sama, tetapi dalam zona waktu yang berbeda-beda:

  • Di London, Inggris Raya: 2019-07-29T18:46:00+01:00
  • Di NYC, AS-NY: 2019-07-29T13:46:00-04:00
  • Di Tokyo, Jepang: 2019-07-30T02:46:00+09:00

Kolom ini diformat sebagai array JSON.

Contoh

Berikut segmen perjalanan penumpang dalam contoh ini:

  • Pada tanggal layanan 20190716, ID penjualan tiket perjalanan ti1 dimulai dari ID penjualan tiket waktu perhentian 11 hingga ID penjualan tiket waktu perhentian 12. Penumpang berangkat pukul 14.00 UTC dan tiba pukul 14.50 UTC.
  • Pada tanggal layanan 20190716, ID penjualan tiket perjalanan ti2 dimulai dari ID penjualan tiket waktu perhentian 21 hingga ID penjualan tiket waktu perhentian 22. Penumpang berangkat pukul 15.00 UTC dan tiba pukul 15.50 UTC.

Untuk contoh ini, web_url adalah https://examplepetstore.com.

Dengan semua informasi ini, gunakan nilai berikut untuk parameter feed untuk perjalanan ini:

Nama kolom Detail
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"]

Berikut URI akhir setelah encoding:

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

Contoh nilai ticketing_stop_id yang berbeda-beda

Perhentian dapat memiliki ID yang berbeda-beda untuk tujuan penjualan tiket dengan kolom ticketing_identifiers.txt. Nilai yang dicetak tebal adalah nilai yang ditemukan di panggilan web yang dideskripsikan setelah file.

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

Jika permintaan dibuat pada 19-07-2019 dan waktu GTFS menggunakan zona waktu UTC+1, berikut panggilan untuk 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

Ikuti rekomendasi berikut untuk menerapkan ekstensi penjualan tiket Google Transit:

Panduan
Bagikan deep link antarperusahaan transportasi umum atau antar-rute jika memungkinkan.

Di feed statis, setiap kali beberapa perusahaan transportasi umum atau rute memiliki URL deep link yang sama, perusahaan transportasi umum atau rute tersebut harus memiliki satu nilai yang sama untuk kolom ticketing_deep_link_id. Hal ini memungkinkan transfer antarperusahaan transportasi umum atau antar-rute.
Tetapkan nilai yang konsisten untuk ticketing_type.

Nilai ticketing_type untuk perhentian tertentu harus konsisten di semua baris dalam file stop_times.txt.
Petakan ticketing_stop_id untuk perhentian induk dan turunan. Lakukan pemetaan untuk semua perhentian induk dan turunan yang memerlukan penjualan tiket. Dalam file ticketing_identifiers.txt, nilai ticketing_stop_id tidak diterapkan antara perhentian induk dan turunannya.
Petakan ticketing_stop_id untuk setiap perusahaan transportasi umum yang menggunakan perhentian yang sama di feed.

Di feed statis, jika beberapa perusahaan transportasi umum yang mengaktifkan penjualan tiket memiliki perhentian yang sama, pemetaan harus ada untuk setiap perusahaan transportasi umum tersebut.

Guna mengetahui detail selengkapnya, lihat bagian Definisi kolom untuk ticketing_identifiers.txt.
Gunakan Link Aplikasi Android jika deep link ke aplikasi Android diperlukan.

Jika partner ingin membuka aplikasi Android dari deep link, siapkan deep link sebagai Link Aplikasi Android.
Gunakan Link Universal iOS jika deep link ke aplikasi iOS diperlukan. Jika partner ingin membuka aplikasi iOS dari deep link, siapkan deep link sebagai Link Universal iOS.