השיטה הזו מספקת קבוצות כרטיסים ברמה גבוהה לנסיעה מסוימת. הם מכילים קבוצות של פלחים עם מחלקות שירות נבחרות שאפשר להזמין בכרטיס אחד, וגם מידע על התעריף והזמינות של הכרטיס כולו. חשוב לדעת:
- כל המזהים ticketing_.*_id (חלק מ-SegmentKey) יפנו למזהים שסופקו בתוסף Google Transit Ticketing.
- המזהים צריכים להיות יציבים, וכל שינוי בהם צריך להיות תואם לאחור, כפי שמצוין בדרישות בנושא שילוב GTFS.
GetTripOptionsRequest
הגדרת פרוטו
// Request sent to partners. message GetTripOptionsRequest { // All segments together should form a single trip for which a ticket can be // booked. repeated ext.travel.transport.partner.SegmentKey segment_keys = 1; }
דוגמה ל-JSON
{ "segment_keys": [ { "ticketing_trip_id": "123456", "from_ticketing_stop_time_id": "ZRH-1234", "to_ticketing_stop_time_id": "LUZ-1235", "service_date": { "year": 2022, "month": 4, "day": 6 }, "boarding_time": { "year": 2022, "month": 4, "day": 6, "hours": 14, "minutes": 25, "seconds": 0, "nanos": 0, "utc_offset": "0s" }, "arrival_time": { "year": 2022, "month": 4, "day": 6, "hours": 16, "minutes": 25, "seconds": 0, "nanos": 0, "utc_offset": "0s" } }, { "ticketing_trip_id": "234567", "from_ticketing_stop_time_id": "LUZ-2759", "to_ticketing_stop_time_id": "WOL-2455", "service_date": { "year": 2022, "month": 4, "day": 6 }, "boarding_time": { "year": 2022, "month": 4, "day": 6, "hours": 18, "minutes": 13, "seconds": 0, "nanos": 0, "utc_offset": "0s" }, "arrival_time": { "year": 2022, "month": 4, "day": 6, "hours": 20, "minutes": 13, "seconds": 0, "nanos": 0, "utc_offset": "0s" } } ] }
GetTripOptionsResponse
הגדרת פרוטו
// Response received from partners. message GetTripOptionsResponse { oneof response { TripOptionsResult trip_options_result = 1; TripOptionsError trip_options_error = 2; } } // A successful partner response. message TripOptionsResult { // Note: // - A TripOption represents the fare for a combination of available service // classes for the segments in the request. // - If the seats within a service class are sold at different fares of // limited availability, a different TripOption instance with the same // sequence of segments can be returned for each fare. // Partners should also include options that are unavailable because they are // fully booked, using the appropriate Unavailable message below. repeated TripOption trip_options = 1; } // A travel option for users covering the whole end-to-end journey with the // partner. message TripOption { // A series of Segments that cover the whole trip option, one for each // SegmentKey in the request. repeated Segment segments = 1; // This is the lowest standard fare of all seats with the specified segments. // This field is optional if the series of segments is unavailable. // This "standard fare" should be the lowest seat price where no age or other // booking restrictions apply. The currency should be the local currency of // the origin of the first segment. Fare lowest_standard_fare = 2; // The availability status for bookings of this trip option at the // lowest_standard_fare. Availability availability = 3; // This is used to receive optional extra data via the Travel Transport API // and pass it into the ticketing deep link. // Booking links should still work without the booking token, but the token // can be used to ensure price consistency between Google Search results and // the partner booking page. string booking_token = 4 [features.field_presence = EXPLICIT]; } // A segment traveled on a single vehicle in a given Service Class. message Segment { SegmentKey segment_key = 1; // The service class used on this segment. ServiceClass service_class = 2; }
דוגמה ל-JSON
{ "trip_options_result": { "trip_options": [ { "segments": [ { "segment_key": { "ticketing_trip_id": "123456", "from_ticketing_stop_time_id": "ZRH-1234", "to_ticketing_stop_time_id": "LUZ-1235", "service_date": { "year": 2022, "month": 4, "day": 6 }, "boarding_time": { "year": 2022, "month": 4, "day": 6, "hours": 14, "minutes": 25, "seconds": 0, "utc_offset": "0s" }, "arrival_time": { "year": 2022, "month": 4, "day": 6, "hours": 16, "minutes": 25, "seconds": 0, "utc_offset": "0s" } }, "service_class": { "type": "FIRST_CLASS" } }, { "segment_key": { "ticketing_trip_id": "234567", "from_ticketing_stop_time_id": "LUZ-2759", "to_ticketing_stop_time_id": "WOL-2455", "service_date": { "year": 2022, "month": 4, "day": 6 }, "boarding_time": { "year": 2022, "month": 4, "day": 6, "hours": 18, "minutes": 13, "seconds": 0, "utc_offset": "0s" }, "arrival_time": { "year": 2022, "month": 4, "day": 6, "hours": 20, "minutes": 13, "seconds": 0, "utc_offset": "0s" } }, "service_class": { "type": "FIRST_CLASS" } } ], "lowest_standard_fare": { "total_amount": { "units": 15, "nanos": 0, "currency_code": "CHF" }, "line_items": [ { "line_item_type": "BASE_FARE", "amount": { "units": 13, "nanos": 950000000, "currency_code": "CHF" } }, { "line_item_type": "SERVICE_CHARGE", "amount": { "units": 1, "nanos": 50000000, "currency_code": "CHF" } } ] }, "availability": { "available": { "available_seat_count": 10, "total_seat_count": 30 } } }, { "segments": [ { "segment_key": { "ticketing_trip_id": "123456", "from_ticketing_stop_time_id": "ZRH-1234", "to_ticketing_stop_time_id": "LUZ-1235", "service_date": { "year": 2022, "month": 4, "day": 6 }, "boarding_time": { "year": 2022, "month": 4, "day": 6, "hours": 14, "minutes": 25, "seconds": 0, "utc_offset": "0s" }, "arrival_time": { "year": 2022, "month": 4, "day": 6, "hours": 16, "minutes": 25, "seconds": 0, "utc_offset": "0s" } }, "service_class": { "type": "SECOND_CLASS" } }, { "segment_key": { "ticketing_trip_id": "234567", "from_ticketing_stop_time_id": "LUZ-2759", "to_ticketing_stop_time_id": "WOL-2455", "service_date": { "year": 2022, "month": 4, "day": 6 }, "boarding_time": { "year": 2022, "month": 4, "day": 6, "hours": 18, "minutes": 13, "seconds": 0, "utc_offset": "0s" }, "arrival_time": { "year": 2022, "month": 4, "day": 6, "hours": 20, "minutes": 13, "seconds": 0, "utc_offset": "0s" } }, "service_class": { "type": "SECOND_CLASS" } } ], "lowest_standard_fare": { "total_amount": { "units": 10, "nanos": 0, "currency_code": "CHF" }, "line_items": [ { "line_item_type": "BASE_FARE", "amount": { "units": 9, "nanos": 750000000, "currency_code": "CHF" } }, { "line_item_type": "SERVICE_CHARGE", "amount": { "units": 0, "nanos": 250000000, "currency_code": "CHF" } } ] }, "availability": { "available": { "available_seat_count": 44, "total_seat_count": 200 } } } ] } }
דוגמה לשגיאת JSON
{ "trip_options_error": { "error_type": "SEGMENT_KEY_NOT_FOUND", "error_message": "No matching segments found, no departures at 14:25" } }
הערה לגבי הטמעה של API:
כדי להבטיח תאימות קדימה לשינויים פוטנציאליים, אם נתקלים בפרמטרים נוספים במפתחות פלחים, צריך תמיד להחזיר אותם בתגובה. אחרת, צריך להתעלם מהפרמטרים ולהתייחס לבקשה כאילו הם לא קיימים, עד שמטמיעים תמיכה ספציפית בפרמטרים.
תגובות שגיאה
בטבלה הבאה מפורטות הציפיות לדיווח על שגיאות בשיטה הזו:
| סוג שגיאה | ניתן לנסות שוב | קוד מצב HTTP | תיאור |
|---|---|---|---|
SEGMENT_KEY_NOT_FOUND |
לא | 404 | לא נמצא פלח שמתאים לאחד ממזהי SegmentKey שסופקו. |
TRIP_OPTION_CACHE_STALE |
כן | 404 | הנתונים של אפשרות הנסיעה המבוקשת לא עדכניים אצל השותף, וצריך לרענן אותם כדי לספק אותם ל-Google. |
INTERNAL_ERROR |
כן | 500 | אירעה שגיאה לא צפויה במהלך אחזור הנסיעה הזו. ההודעה הזו מצביעה על באג שהשותף צריך לתקן. |
SUBOPTIMAL_ITINERARY |
לא | 404 | הנסיעה נמצאה, אבל השותף חושב שהיא לא אופטימלית ובחר לא למכור כרטיסים לנסיעה הזו. |
TICKETING_PROHIBITED |
לא | 404 | המערכת מצאה את הנסיעה, אבל השותף לא מורשה למכור כרטיסים לנסיעה הזו בגלל הגבלות כלליות על מכירת כרטיסים שהוטלו על ידי המפעיל או רשות הרכבות. |
BOOKING_WINDOW_NOT_SUPPORTED |
לא | 404 | השותף לא תומך בתמחור מסלולי נסיעה לתאריך המבוקש. |
פרטים נוספים זמינים במאמר TripOptionsErrorType
למידע על החזרת קוד סטטוס בתגובות HTTP, אפשר לעיין במאמר בנושא קודי סטטוס וטיפול בשגיאות.