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

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

דרישות

השדה departure_time בטבלה stop_times.txt הוא שדה חובה.

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

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

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

סיומות או סיומות קבצים

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

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

שם הקובץ ארץ מגדיר
agency.txt תוסף הוספה של agency.ticketing_deep_link_id.
routes.txt תוסף הוספה של routes.ticketing_deep_link_id.
trips.txt תוסף הוספה של trips.trip_ticketing_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) מגדיר את קישור העומק שישמש עבור הסוכנות הזו. ניתן להחלפה ב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 אופציונלי

(כתובת אתר) כתובת האתר של הקישור האוניברסלי להפעלה ב-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
  • בניו יורק, ארה"ב-ניו יורק: 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,"פריז 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, זו הקריאה לאינטרנט:

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.