توفّر هذه الطريقة مجموعات تذاكر عالية المستوى لرحلة محدّدة. تحتوي هذه الفئات على مجموعات من الشرائح مع فئات خدمات محدّدة يمكن حجزها على التذكرة نفسها، بالإضافة إلى معلومات عن الأجرة ومدى التوفّر للتذكرة ككل. يُرجى ملاحظة ما يلي:
- ستشير جميع المعرّفات ticketing_.*_id (وهي جزء من SegmentKey) إلى المعرّفات المقدَّمة في إضافة Google Transit Ticketing.
- يجب أن تكون المعرّفات ثابتة، ويجب أن تكون أي تغييرات يتم إجراؤها عليها متوافقة مع الإصدارات السابقة كما هو مذكور في متطلبات دمج GTFS.
GetTripOptionsRequest
تعريف Proto
// 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
تعريف Proto
// 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" } }
ملاحظة حول تنفيذ واجهة برمجة التطبيقات:
لضمان التوافق مع التغييرات المحتملة، إذا تم العثور على مَعلمات إضافية في مفاتيح الأقسام، يجب دائمًا إرجاعها في الردّ. في ما عدا ذلك، تجاهِل المَعلمات وتعامل مع الطلب كما لو أنّه لم يتم تضمينها، إلى أن توفّر دعمًا مخصّصًا لها.
ردود الأخطاء
يوضّح الجدول التالي توقعات إعداد تقارير الأخطاء لهذه الطريقة:
| نوع الخطأ | قابلة لإعادة المحاولة | رمز حالة 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، يُرجى الرجوع إلى رموز الحالة والتعامل مع الأخطاء.