ส่วนขยายการจำหน่ายตั๋วของ Google Transit

หน้านี้กำหนดชุดย่อยของข้อกำหนด GTFS-Ticketing ซึ่งอยู่ในขั้นเสนอในระหว่างการสร้างเอกสารนี้ หน้านี้ยังมีข้อจํากัดเพิ่มเติมอีกหลายประการจาก Google ด้วย

ข้อกำหนด

ต้องกรอกข้อมูลในช่อง departure_time ใน stop_times.txt

ประเภทฟิลด์เพิ่มเติม

ส่วนนี้จะอธิบายประเภทช่องเพิ่มเติมและช่องที่มีส่วนขยายจาก Google ช่องบางช่องกำหนดให้ค่าอยู่ในรูปแบบ URI

  • URI: Uniform Resource Identifier (URI) ที่สมบูรณ์ซึ่งมีรูปแบบ สัญลักษณ์พิเศษใน URI ต้องกำหนดเป็นอักขระหลีกอย่างถูกต้อง ดูคำอธิบายวิธีสร้างค่า URI ที่สมบูรณ์ในตัวเองได้ที่ RFC 3986 Uniform Resource Identifier (URI): ไวยากรณ์ทั่วไป

นามสกุลไฟล์หรือส่วนเพิ่มเติม

ไฟล์ข้อความที่มีสถานะขยายคือไฟล์ที่มีอยู่แล้วและคุณจำเป็นต้องขยาย คุณต้องเพิ่มฟิลด์ใหม่ที่เราได้กำหนดไว้ในตารางต่อไปนี้

ไฟล์ข้อความที่มีสถานะการเพิ่มคือไฟล์ใหม่ที่ส่วนขยายการจำหน่ายตั๋วของ Google Transit เปิดตัว คุณต้องสร้างไฟล์เหล่านี้ตามคำจำกัดความของฟิลด์ที่ระบุไว้หลังตารางต่อไปนี้ อย่าลืมใส่ไฟล์เหล่านี้ในฟีด

ชื่อไฟล์ รัฐ กำหนด
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 ไม่บังคับ

(รหัสจาก ticketing_deep_links.txt) กําหนด Deep Link ที่จะใช้สําหรับเอเจนซีนี้ เขียนทับได้ใน routes.txt

routes.txt (ไฟล์ขยาย)

ชื่อช่อง การมีบุคคลอยู่ รายละเอียด
ticketing_deep_link_id ไม่บังคับ (รหัสจาก ticketing_deep_links.txt) กําหนด Deep Link ที่จะใช้สําหรับเส้นทางนี้ หากมี จะเขียนทับช่องใน agency.txt

trips.txt (ไฟล์ขยาย)

ชื่อช่อง การมีบุคคลอยู่ รายละเอียด
ticketing_trip_id ไม่บังคับ

(ID) ตัวระบุที่จะส่งใน Deep Link โดยไม่จำเป็นต้องซ้ำกัน

หาก ticketing_trip_id ว่างเปล่า ระบบจะใช้ค่าของ trip_id แทน
ticketing_type ไม่บังคับ

(Enum) กำหนดว่าการซื้อตั๋วผ่าน Deep Link พร้อมใช้งานสำหรับการเดินทางนี้หรือไม่

  • 0 หรือว่างเปล่า
    • หากกำหนด ticketing_deep_link_id สำหรับเส้นทางหรือเอเจนซี ตัวเลือกนี้จะพร้อมใช้งาน
    • ไม่พร้อมใช้งาน
  • 1: ไม่พร้อมใช้งาน

stop_times.txt (ไฟล์ขยาย)

ชื่อช่อง การมีบุคคลอยู่ รายละเอียด
ticketing_type ไม่บังคับ

(Enum) กำหนดว่าจุดจอดรถนี้อนุญาตให้ซื้อตั๋วผ่าน Deep Link ได้หรือไม่ หากคุณกำหนด stop_times.ticketing_type ค่านี้จะลบล้างค่าที่ตั้งไว้ใน trip.ticketing_type

  • ว่าง: ใช้ค่าจาก trip.ticketing_type
  • 0:
    • หากกำหนด ticketing_deep_link_id สำหรับเส้นทางหรือเอเจนซี ตัวเลือกนี้จะพร้อมใช้งาน
    • ไม่พร้อมใช้งาน
  • 1: ไม่พร้อมใช้งาน

ticketing_identifiers.txt (เพิ่มไฟล์แล้ว)

กรณีที่พบบ่อยที่สุดสำหรับตั๋วคือทุกป้ายจอดรถมีตัวระบุเพื่อประมวลผลการเรียกเก็บเงิน หน่วยงานต่างๆ อาจใช้ตัวระบุเดียวกันกับป้ายจอดรถหนึ่งๆ เมื่อเอเจนซีหลายรายให้บริการที่ป้ายจอดรถเดียวกัน ให้ทำแผนที่นี้ซ้ำสำหรับเอเจนซีแต่ละราย

ชื่อช่อง การมีบุคคลอยู่ รายละเอียด
ticketing_stop_id จำเป็น (ID) กําหนดรหัสตั๋วเริ่มต้นสําหรับป้ายจอดรถนี้สําหรับเอเจนซีนี้
stop_id จำเป็น (รหัสจาก stops.txt) จุดจอดรถที่กำหนด ticketing_stop_id เริ่มต้นไว้
agency_id จำเป็น (รหัสจาก agency.txt) เอเจนซีของป้ายจอดรถที่กำหนด ticketing_stop_id เริ่มต้นไว้

ticketing_deep_links.txt (เพิ่มไฟล์แล้ว)

ชื่อช่อง การมีบุคคลอยู่ รายละเอียด
ticketing_deep_link_id จำเป็น (ID) กําหนดรหัสสําหรับ Deep Link
web_url ไม่บังคับ

(URL) URL ที่จะเข้าชมสําหรับการทำ Deep Link

ช่องนี้แปลผ่าน translations.txt ไม่ได้
android_intent_uri ไม่บังคับ

(URI) URI ที่ส่งไปยังแอป Android เนทีฟที่มี Intent android.intent.action.VIEW

หากเป็นค่าว่าง หมายความว่าคุณจะทำการ Deep Link ไปยังแอป Android เนทีฟไม่ได้

ดูข้อมูลเพิ่มเติมเกี่ยวกับ Deep Link ใน Android ได้ที่สร้าง Deep Link ไปยังเนื้อหาแอป

ช่องนี้แปลผ่าน translations.txt ไม่ได้
ios_universal_link_url ไม่บังคับ

(URL) URL ของ Universal Link ที่จะเรียกใช้ใน iOS

หากช่องนี้ว่างเปล่า การทำ Deep Link จะไม่แสดงใน iOS

ดูข้อมูลเพิ่มเติมได้ที่Universal Link ใน iOS

ช่องนี้แปลผ่าน translations.txt ไม่ได้

ตัวยึดตําแหน่งช่องในการเรียก API

Google จะเรียกใช้ URL ที่กําหนดไว้ใน ticketing_deep_links.txt ด้วยพารามิเตอร์ต่อไปนี้

ชื่อช่อง รายละเอียด
service_date

(วันที่ซ้ำได้) วันให้บริการของการเดินทาง

ใช้ช่องนี้สำหรับวันที่ที่การเดินทางออกเดินทางจากจุดจอดแรก

ช่องนี้มีการจัดรูปแบบเป็นอาร์เรย์ JSON
ticketing_trip_id

(รหัสจาก trips.txt ซ้ำได้) ตัวระบุของการเดินทาง

ช่องนี้มีการจัดรูปแบบเป็นอาร์เรย์ JSON
from_ticketing_stop_time_id

(ซ้ำได้) ตัวระบุ stop_time ที่เริ่มต้นเส้นทาง

ค่าของเวลาสิ้นสุดที่เฉพาะเจาะจงมีดังนี้

  • ticketing_stop_id ที่กําหนดไว้ใน ticketing_identifiers.txt สำหรับ agency_id และ stop_id ของ stop_time

  • ไม่เช่นนั้น ระบบจะใช้ stop_sequence

ช่องนี้มีการจัดรูปแบบเป็นอาร์เรย์ JSON
to_ticketing_stop_time_id

(ซ้ำได้) ตัวระบุ stop_time ที่ขาสิ้นสุด

ดูคำอธิบายเกี่ยวกับที่มาของค่าได้ที่ from_ticketing_stop_time_id

ช่องนี้มีการจัดรูปแบบเป็นอาร์เรย์ JSON
boarding_time

(ISO 8601, ซ้ำได้) เวลาออกเดินทาง departure_time ของ stop_time ที่เริ่มต้นเที่ยวบิน

ใช้ช่องนี้สำหรับวันที่และเวลาที่ผู้โดยสารขึ้นรถ

ค่าเวลาของช่องนี้เป็นไปตาม ISO 8601 โดยมีรูปแบบสตริงดังต่อไปนี้

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

เวลาทั้งหมดด้านล่างนี้เหมือนกัน เพียงแต่อยู่ในเขตเวลาที่แตกต่างกัน

  • ในลอนดอน สหราชอาณาจักร: 2019-07-29T18:26:00+01:00
  • ในนิวยอร์กซิตี สหรัฐอเมริกา: 2019-07-29T13:26:00-04:00
  • ในโตเกียว ญี่ปุ่น: 2019-07-30T02:26:00+09:00

ช่องนี้มีการจัดรูปแบบเป็นอาร์เรย์ JSON
arrival_time

(ISO 8601, ซ้ำได้) เวลาถึงจุดหมาย arrival_time ที่ stop_time ซึ่งขาการเดินทางสิ้นสุดลง

ค่าเวลาของช่องนี้เป็นไปตาม ISO 8601 ที่มีรูปแบบสตริงดังต่อไปนี้

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

เวลาทั้งหมดด้านล่างนี้เหมือนกัน เพียงแต่อยู่ในเขตเวลาที่แตกต่างกัน

  • ในลอนดอน สหราชอาณาจักร: 2019-07-29T18:46:00+01:00
  • ในนิวยอร์ก สหรัฐอเมริกา: 2019-07-29T13:46:00-04:00
  • ในโตเกียว ญี่ปุ่น: 2019-07-30T02:46:00+09:00

ช่องนี้มีการจัดรูปแบบเป็นอาร์เรย์ JSON

ตัวอย่าง

ในตัวอย่างนี้ เส้นทางของผู้โดยสารมีดังนี้

  • ในวันที่ให้บริการ 20190716 รหัสตั๋วการเดินทาง ti1 เริ่มต้นจากรหัสตั๋วเวลาหยุด 11 ไปจนถึงรหัสตั๋วเวลาหยุด 12 ผู้โดยสารขึ้นเครื่องเวลา 14:00 น. (UTC) และถึงเวลา 14:50 น. (UTC)
  • ในวันที่ให้บริการ 20190716 รหัสตั๋วการเดินทาง ti2 เริ่มต้นจากรหัสตั๋วเวลาหยุด 21 ไปจนถึงรหัสตั๋วเวลาหยุด 22 ผู้เดินทางขึ้นเครื่องเวลา 15:00 น. (UTC) และถึงเวลา 15:50 น. (UTC)

ในตัวอย่างนี้ 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 ค่าที่เป็นตัวหนาคือค่าที่พบในการเรียกใช้เว็บที่อธิบายไว้หลังไฟล์

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

หากคำขอส่งในวันที่ 19-07-2019 และเวลา 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 Transit

หลักเกณฑ์
แชร์ Deep Link ระหว่างเอเจนซีหรือเส้นทางต่างๆ เมื่อเป็นไปได้

ในฟีดแบบคงที่ เมื่อเอเจนซีหรือเส้นทางหลายแห่งมี URL ของ Deep Link เดียวกัน จะต้องแชร์ค่าเดียวสำหรับช่อง ticketing_deep_link_id ซึ่งจะช่วยให้โอนระหว่างเอเจนซีหรือเส้นทางได้
กําหนดค่าที่สอดคล้องกันสําหรับ ticketing_type

ค่า ticketing_type สำหรับป้ายจอดรถหนึ่งๆ ต้องสอดคล้องกันในทุกแถวในไฟล์ stop_times.txt
แมป ticketing_stop_id สําหรับทั้งป้ายจอดรถหลักและป้ายจอดรถย่อย ทำการแมปสำหรับป้ายจอดรถหลักและป้ายจอดรถย่อยทั้งหมดที่ต้องซื้อตั๋ว ในไฟล์ ticketing_identifiers.txt ค่า ticketing_stop_id จะไม่นำไปใช้กับป้ายหยุดหลักและป้ายหยุดย่อย
จับคู่ ticketing_stop_id สำหรับแต่ละเอเจนซีที่ใช้ป้ายจอดรถเดียวกันในฟีด

ในฟีดแบบคงที่ หากเอเจนซีหลายรายที่เปิดใช้การจำหน่ายตั๋วใช้ป้ายจอดรถเดียวกัน แต่ละเอเจนซีต้องมีการแมป

ดูรายละเอียดเพิ่มเติมได้ที่ส่วนคำจำกัดความของช่องสำหรับ ticketing_identifiers.txt
ใช้ Android App Link เมื่อจำเป็นต้องใช้ Deep Link ไปยังแอป Android

หากพาร์ทเนอร์ต้องการเปิดแอป Android จาก Deep Link ให้ตั้งค่า Deep Link เป็น App Link ของ Android
ใช้ Universal Link ของ iOS เมื่อจำเป็นต้องใช้ Deep Link ไปยังแอป iOS หากพาร์ทเนอร์ต้องการเปิดแอป iOS จาก Deep Link ให้ตั้งค่า Deep Link เป็น iOS Universal Link