תוספי מכירת כרטיסים של Google Transit

בדף הזה מוגדרת קבוצת משנה של מפרט GTFS-Ticketing, שנמצא בשלב ההצעה במהלך יצירת המסמך הזה. הדף הזה כולל גם כמה הגבלות נוספות מאת Google.

דרישות

השדה departure_time ב-stop_times.txt הוא חובה.

סוגי שדות נוספים

בקטע הזה מתוארים סוגי השדות הנוספים וסוגי השדות עם תוספים מ-Google. במידה מסוימת נדרשים ערכים בצורת URI.

  • URI: מזהה משאבים אחיד (URI) שמוגדר במלואו שכולל את הסכמה. כלשהו בתווים המיוחדים ב-URI חייבים להשתמש בתו בריחה (escape) הנכונים. לתיאור של אופן היצירה כל ערכי ה-URI הנכונים. מידע נוסף זמין בכתובת RFC 3986 Uniform Resource Identifier (URI): גנרי תחביר.

סיומות או תוספות של קבצים

קובצי הטקסט עם תוסף המצב הם קבצים שכבר קיימים ועליך להאריך. עליכם להוסיף את השדות החדשים שאנחנו מגדירים בטבלה הבאה.

קובצי הטקסט עם המדינה הוספה הם קבצים חדשים שנוספו על ידי Google Transit תוספי מכירת כרטיסים. צריך ליצור את הקבצים האלה בהתאם הגדרות השדות שמופיעות אחרי הטבלה הבאה. חשוב כוללים את הקבצים האלה בפיד.

שם הקובץ מדינה הגדרות
agency.txt Extension הוספה של agency.ticketing_deep_link_id.
routes.txt Extension הוספה של routes.ticketing_deep_link_id.
trips.txt Extension הוספה של trips.ticketing_trip_id ושל trips.ticketing_type.
stop_times.txt Extension הוספה של stop_times.ticketing_type.
ticketing_identifiers.txt תוספת קובץ חדש. מידע נוסף זמין במאמר הגדרות שדות.
ticketing_deep_links.txt תוספת קובץ חדש. מידע נוסף זמין במאמר הגדרות שדות.

הגדרות של שדות

agency.txt (הקובץ הוארך)

שם השדה נוכחות פרטים
ticketing_deep_link_id אופציונלי

(מזהה מ-ticketing_deep_links.txt) מגדיר את קישור העומק שישמש לפעולה הזו שלך. ניתן להחלפה בroutes.txt.

routes.txt (הקובץ הוארך)

שם השדה נוכחות פרטים
ticketing_deep_link_id אופציונלי (מזהה מ-ticketing_deep_links.txt) מגדיר את קישור העומק שישמש לפעולה הזו מסלול. אם השדה קיים, האפשרות הזו תחליף את השדה ב-agency.txt.

trips.txt (הקובץ הוארך)

שם השדה נוכחות פרטים
ticketing_trip_id אופציונלי

(מזהה) מזהה שצריך להעביר בקישור העומק. לא חייבת להיות ייחודית.

אם השדה ticketing_trip_id ריק, המערכת תשתמש בערך של trip_id במקום זאת.
ticketing_type אופציונלי

(Enum) מגדירים אם אפשר לרכוש כרטיסים באמצעות קישור עומק בנסיעה הזו:

  • 0 או ריק:
    • אם מגדירים ticketing_deep_link_id למסלול או לסוכנות, הערך הוא זמינים.
    • לא זמין אחרת.
  • 1: לא זמינה.

stop_times.txt (הקובץ הוארך)

שם השדה נוכחות פרטים
ticketing_type אופציונלי

(Enum) מגדיר אם מכירת כרטיסים באמצעות קישור עומק זמין בזמן העצירה הזה. אם המיקום שמגדירים את 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) מגדיר מזהה לקישור העומק.
web_url אופציונלי

(כתובת URL) כתובת ה-URL שצריך להיכנס אליה עבור קישורי עומק.

אי אפשר לתרגם את השדה הזה דרך translations.txt.
android_intent_uri אופציונלי

(URI) ה-URI להעברה לאפליקציה מקורית ל-Android עם Intent מסוג android.intent.action.VIEW.

אם היא ריקה, אי אפשר לבצע קישור עומק לאפליקציה מקורית ל-Android.

למידע נוסף על קישורי עומק ב-Android, אפשר לעיין במאמר יצירת קישורי עומק אל תוכן האפליקציה.

אי אפשר לתרגם את השדה הזה דרך translations.txt.
ios_universal_link_url אופציונלי

(כתובת URL) כתובת ה-URL של הקישור האוניברסלי להפעלה ב-iOS.

אם השדה ריק, קישורי העומק לא יוצגו ב-iOS.

מידע נוסף זמין במאמר קישורים אוניברסליים ב-iOS.

אי אפשר לתרגם את השדה הזה דרך translations.txt.

placeholders של שדות בקריאה ל-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
  • בניו יורק, US-NY: 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,"פריז גאר-דה-ליון"

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 ביולי 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:

הנחיות
כדאי לשתף קישורי עומק בין סוכנויות או מסלולים ככל האפשר.

בפיד הסטטי, בכל פעם שכמה סוכנויות או מסלולים כוללים את אותן כתובות URL של קישורי עומק, הם צריכים לשתף ערך יחיד בשדה 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 כשנדרש קישור עומק לאפליקציה ל-Android.

אם השותף רוצה לפתוח אפליקציה ל-Android מקישור עומק, יש להגדיר את קישור העומק בתור קישור לאפליקציה ל-Android.
משתמשים בקישורים אוניברסליים ל-iOS כשנדרש קישור עומק לאפליקציה ל-iOS. אם השותף רוצה לפתוח אפליקציה ל-iOS מקישור עומק, צריך להגדיר את קישור העומק בתור קישור אוניברסלי ל-iOS.