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

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

דרישות

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

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

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

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

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

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

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

שם הקובץ מדינה הגדרה
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 חובה (מזהה) מגדיר מזהה ברירת מחדל לכרטיסים של התחנה הזו עבור החברה הזו.
stop_id חובה (מזהה מ-stops.txt) התחנה שבה מוגדרת ברירת המחדל ticketing_stop_id.
agency_id חובה (מזהה מ-agency.txt) הסוכנות של התחנה שבה מוגדר ticketing_stop_id כברירת מחדל.

ticketing_deep_links.txt (הקובץ נוסף)

שם השדה נוכחות פרטים
ticketing_deep_link_id חובה (מזהה) הגדרת מזהה של קישור העומק.
web_url אופציונלי

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

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

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

אם השדה ריק, המשמעות היא שלא ניתן ליצור קישור עומק לאפליקציה מקורית ל-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
  • בניו יורק, ארה"ב-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,"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 ביולי 2019 והשעות ב-GTFS הן באזור הזמן UTC+1, הקריאה הבאה היא ל-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

כדי להטמיע תוספים של כרטיסים ל-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.