يوفر مسار النقل العام تعليمات التنقل باستخدام خيارات وسائل النقل العام المتاحة في المنطقة. قد تشمل خيارات النقل العام الحافلات ومترو الأنفاق والقطارات، من بين خيارات أخرى. عادة ما يتضمن مسار النقل العام أيضًا تعليمات حول السير من محطات النقل العام ومنها وبينها. نظرًا لأن مسار النقل العام يتطلب منك عادةً السفر باستخدام أكثر من وسيلة نقل واحدة، ستختلف كيفية طلب المسار وبعض أجزاء الاستجابة.
أوجه الاختلاف بين مسارات النقل العام والمسارات الأخرى
تختلف مسارات النقل العام التي تطلبها من خلال تعيين وضع Travel Mode (وضع TRANSIT) عن المسارات التي تستخدم خيارات TravelMode المختلفة. لا يمكنك طلب جميع العناصر والخيارات نفسها، وسيتم عرض حقول مختلفة في الاستجابة، عند مقارنتها بالمسارات الأخرى.
في Routes API، تشكّل الخطوات بشكل متناسق تعليمات تنقّل واحدة في جميع أنواع الرحلات. لذا فإن كل تعليمات تنقل عبارة عن خطوة. وتشبه استجابة مسار النقل العام إلى حد كبير المسارات التي بها وسائل نقل أخرى، مع بعض الاختلافات الرئيسية:
| الاختلافات في الطلبات | الاختلافات في الردود |
|---|---|
| لا يمكنك تحديد نقاط الطريق المتوسطة. | يتضمن تفاصيل النقل العام. |
| يتعذّر الحصول على مسارات صديقة للبيئة. | يتم تضمين بيانات وصفية لكل وسيلة نقل تحتوي على ملخّص للخطوات الخاصة بوضع السفر هذا في "stepsOverview" في "stepsOverview" (لطلب هذه البيانات الوصفية، استخدِم قناع الحقل "routes.legs.stepsOverview"). |
| لا يمكن تحديد كيفية تضمين بيانات حركة المرور أو لا | |
| لا يمكن تحديد ميزات المسار المطلوب تجنبها | |
يمكن فقط تحديد السمة transitPreferences للسمة
routingPreference. لمعرفة التفاصيل، يمكنك الاطّلاع على
[TransitPreferences](reference/rest/v2/transitPreferences). |
للمزيد من المعلومات عن الاستجابة التي تعرضها واجهة Routes API، يُرجى الاطّلاع على المقالة مراجعة ردود مسارات النقل العام.
للحصول على مسار نقل عام
حدِّد نقطة الانطلاق والوجهة.
ضبط وضع السفر على النقل العام:
travelMode: "TRANSIT"أضِف قناع حقل للحصول على حقول الرد التي تريدها. يمكنك الاطّلاع على طلب حقول مسارات النقل العام التي تحتاج إليها.
اضبط مَعلمات اختيارية إذا لزم الأمر. اطّلِع على مقالة ضبط مَعلمات لمسار نقل عام.
طلب حقول مسارات النقل العام التي تحتاج إليها
اطلب حقول مسارات النقل العام التي تحتاج إليها باستخدام أقنعة الحقول. يحتوي الجدول التالي على بعض الردود المقترحة لمسار النقل العام، وقناع الحقل الذي يمكن استخدامه لطلبها.
| لطلب هذه المعلومات | استخدام قناع الحقل هذا |
|---|---|
| كل تفاصيل المسارات | routes.* |
| جميع تفاصيل النقل العام | routes.legs.steps.transitDetails |
| موقع البدء لكل ساق | routes.legs.steps.startLocation |
| موقع الانتهاء لكل ساق | routes.legs.steps.endLocation |
| الخط المتعدد للمسار لكل خطوة | routes.legs.steps.polyline |
| نوع النقل العام المُستخدَم لكل خطوة | routes.legs.steps.travelMode |
| الأجرة المقدّرة لكل خطوة والمسار والسعر التقديري المترجَم | routes.travel_advisory.transitFare
localized routes.localizedValues.transitFare
ملاحظة: لا يتم توفير |
| نص مترجَم للمدة والمسافة | routes.localizedValues |
لمزيد من المعلومات حول إعداد أقنعة الحقول، راجِع اختيار الحقول المطلوب عرضها.
ضبط المعلمات لمسار نقل عام
في ما يلي المَعلمات ذات الصلة بمسارات النقل العام:
| لتنفيذ هذا الإجراء | استخدام هذه المَعلمة | Notes |
|---|---|---|
| اختيار وضع النقل العام | travelMode: "TRANSIT" |
مطلوبة. مزيد من المعلومات |
| تحديد وقت الوصول أو المغادرة | "arrivalTime": "yyyy-mm-ddThh:mm:ssZ"
أو "departureTime": "yyyy-mm-ddThh:mm:ssZ" |
اختياريّ. يمكنك تحديد وقت الوصول أو وقت المغادرة. وفي حال عدم تحديد أي من الوقتين، سيتم ضبط وقت التنفيذ التلقائي لـ departure_time على وقت التنفيذ الحالي (now). ولا يمكنك ضبط وقت الوصول والمغادرة إلا خلال الفترة الزمنية التالية، مع استخدام وقت التنفيذ الحالي (now) كمرجع:
|
| تضمين مسارات بديلة | "computeAlternativeRoutes": true |
اختياريّ. اضبط القيمة على "صحيح" لكي تحسب واجهة Routes API ما يصل إلى 3 مسارات إضافية، عند توفّرها. مزيد من المعلومات |
| تحديد الإعدادات المفضّلة لنوع النقل العام | "transitPreferences": { allowedTravelModes: ["BUS","SUBWAY","TRAIN","LIGHT_RAIL","RAIL"]}
ملاحظة: في حال تحديد وسيلة نقل مفضَّلة، قد تبقى المسارات التي ترجعها تستخدم وسائل نقل عام أخرى، وقد تستخدم أوضاعًا نقل عام أخرى فقط، وذلك استنادًا إلى كفاءة المسار ومدى توفّرها. |
اختياريّ. تحديد وسائل النقل المفضّلة لديك في وسائل النقل العام مزيد من المعلومات |
| تحديد الإعدادات المفضّلة لمسار النقل العام | "transitPreferences": {routingPreference: "LESS_WALKING|FEWER_TRANSFERS"} |
اختياريّ. تحديد الإعدادات المفضّلة لتوجيه النقل العام مزيد من المعلومات |
مثال: الحصول على مسار للنقل العام
يوضح المثال التالي مسارًا للنقل العام مع المعلمات التالية:
تحدِّد هذه السمة الإعدادات المفضّلة للسفر بالقطار ومشيًا أقل.
تطلب مسارات بديلة.
لتوفير قناع حقل يعرض تفاصيل النقل العام:
curl -X POST -H 'content-type: application/json' -d '{
"origin": {
"address": "Humberto Delgado Airport, Portugal"
},
"destination": {
"address": "Basílica of Estrela, Praça da Estrela, 1200-667 Lisboa, Portugal"
},
"travelMode": "TRANSIT",
"computeAlternativeRoutes": true,
"transitPreferences": {
routingPreference: "LESS_WALKING",
allowedTravelModes: ["TRAIN"]
},
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.legs.steps.transitDetails' \
'https://routes.googleapis.com/directions/v2:computeRoutes'
يعرِض الردّ حقول route.legs.steps.transitDetails للمسارَين:
{
"routes": [
{
"legs": [
{
"steps": [
{},
{},
{},
{
"transitDetails": {
"stopDetails": {
"arrivalStop": {
"name": "Saldanha",
"location": {
"latLng": {
"latitude": 38.73532,
"longitude": -9.14543
}
}
},
"arrivalTime": "2023-08-26T10:49:42Z",
"departureStop": {
"name": "Aeroporto",
"location": {
"latLng": {
"latitude": 38.769047799999996,
"longitude": -9.1284593
}
}
},
"departureTime": "2023-08-26T10:32:10Z"
},
"localizedValues": {
"arrivalTime": {
"time": {
"text": "11:49"
},
"timeZone": "Europe/Lisbon"
},
"departureTime": {
"time": {
"text": "11:32"
},
"timeZone": "Europe/Lisbon"
}
},
"headsign": "São Sebastião",
"transitLine": {
"agencies": [
{
"name": "Metropolitano de Lisboa, E.P.E.",
"phoneNumber": "+351 21 350 0115",
"uri": "https://www.metrolisboa.pt/"
}
],
"name": "Vermelha",
"color": "#f23061",
"nameShort": "Vm",
"textColor": "#000000",
"vehicle": {
"name": {
"text": "Metrô"
},
"type": "SUBWAY",
"iconUri": "//maps.gstatic.com/mapfiles/transit/iw2/6/subway2.png"
}
},
"stopCount": 11
}
},
{},
{
"transitDetails": {
"stopDetails": {
"arrivalStop": {
"name": "Rato",
"location": {
"latLng": {
"latitude": 38.7201022,
"longitude": -9.1540562
}
}
},
"arrivalTime": "2023-08-26T11:01:37Z",
"departureStop": {
"name": "Saldanha",
"location": {
"latLng": {
"latitude": 38.73527,
"longitude": -9.1455200000000012
}
}
},
"departureTime": "2023-08-26T10:57:57Z"
},
"localizedValues": {
"arrivalTime": {
"time": {
"text": "12:01"
},
"timeZone": "Europe/Lisbon"
},
"departureTime": {
"time": {
"text": "11:57"
},
"timeZone": "Europe/Lisbon"
}
},
"headsign": "Rato",
"transitLine": {
"agencies": [
{
"name": "Metropolitano de Lisboa, E.P.E.",
"phoneNumber": "+351 21 350 0115",
"uri": "https://www.metrolisboa.pt/"
}
],
"name": "Amarela",
"color": "#f2c200",
"nameShort": "Am",
"textColor": "#000000",
"vehicle": {
"name": {
"text": "Metrô"
},
"type": "SUBWAY",
"iconUri": "//maps.gstatic.com/mapfiles/transit/iw2/6/subway2.png"
}
},
"stopCount": 4
}
},
{},
{},
{},
{},
{},
{}
]
}
]
}
]
}