الحصول على مسار النقل العام

يوفر مسار النقل العام تعليمات التنقل باستخدام خيارات وسائل النقل العام المتاحة في المنطقة. قد تشمل خيارات النقل العام الحافلات ومترو الأنفاق والقطارات، من بين خيارات أخرى. عادةً ما يتضمن مسار النقل العام أيضًا إرشادات حول المشي من محطات النقل العام ومنها وبينها. نظرًا لأنّ مسار النقل العام يتطلب منك عادةً السفر باستخدام أكثر من وسيلة نقل واحدة، ستختلف كيفية طلب المسار وبعض أجزاء الاستجابة.

مدى اختلاف مسارات النقل العام عن المسارات الأخرى

تختلف مسارات النقل العام، التي تطلبها من خلال تعيين TravelMode لـ TRANSIT، عن المسارات التي تستخدم خيارات TravelMode المختلفة. ولا يمكنك طلب جميع الكائنات والخيارات نفسها، وتعرض الاستجابة حقولاً مختلفة، مقارنةً بالمسارات الأخرى.

في Routes API، تمثّل الخطوات باستمرار تعليمات تنقّل واحدة عبر جميع أنواع الرحلات. لذا فإن كل تعليمة تنقل عبارة عن خطوة. وتشبه استجابة مسار النقل العام إلى حد كبير المسارات التي تتضمن أوضاع السفر الأخرى، مع بعض الاختلافات الرئيسية:

الاختلافات في الطلبات	الاختلافات في الردود
لا يمكنك تحديد نقاط الطريق المتوسطة.	تتضمّن تفاصيل النقل العام.
يتعذّر الحصول على مسارات صديقة للبيئة.	يتضمن البيانات الوصفية لكل وسيلة سفر تتضمن ملخّصًا للخطوات الخاصة بوضع السفر هذا في "stepsOverview" (لطلب هذه البيانات الوصفية، استخدِم قناع الحقل "routes.legs.stepsOverview").
لا يمكن تحديد كيفية تضمين بيانات حركة المرور وما إذا كان سيتم تضمينها
لا يمكن تحديد ميزات المسار التي يجب تجنُّبها
يمكن فقط تحديد السمة transitPreferences للسمة routingPreference. لمعرفة التفاصيل، يُرجى الاطّلاع على [TransitPreferences](reference/rest/v2/TransitPreferences).

لمزيد من المعلومات حول الردود التي تعرضها واجهة برمجة تطبيقات Routes API، يُرجى الاطّلاع على مقالة مراجعة الردود الخاصة بمسارات النقل العام.

للحصول على مسار نقل عام

1. اضبط نقطة الانطلاق والوجهة.

2. ضبط وضع السفر على النقل العام:

   travelMode: "TRANSIT"

3. أضِف قناع حقل للحصول على حقول الردود التي تريدها. راجِع اطلب حقول مسارات النقل العام التي تحتاجها.

4. اضبط المَعلمات الاختيارية إذا لزم الأمر. اطّلِع على ضبط المَعلمات لمسار نقل عام.

طلب حقول مسار النقل العام التي تحتاجها

اطلب حقول مسار النقل العام التي تحتاجها باستخدام أقنعة الحقول. يحتوي الجدول التالي على بعض الردود المقترحة لمسار النقل العام وقناع الحقل الذي يمكن استخدامه لطلبها.

لطلب هذه المعلومات:	استخدام قناع الحقل هذا
جميع تفاصيل المسارات	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 ملاحظة: لا يتم توفير transitFare إلا إذا كان بإمكان واجهة برمجة التطبيقات تحديد معلومات أسعار النقل العام لكل الخطوات.
نص تمت ترجمته للمدة والمسافة	routes.localizedValues

لمزيد من المعلومات حول ضبط أقنعة الحقول، يُرجى الاطّلاع على اختيار الحقول المطلوب عرضها.

ضبط المعلمات لمسار نقل عام

في ما يلي المَعلمات ذات الصلة لمسارات النقل العام:

للقيام بذلك،	استخدام هذه المَعلمة	Notes
اختيار وضع النقل العام	travelMode: "TRANSIT"	مطلوبة. مزيد من المعلومات
تحديد وقت الوصول أو المغادرة	"arrivalTime": "yyyy-mm-ddThh:mm:ssZ" أو "departureTime": "yyyy-mm-ddThh:mm:ssZ"	اختياريّ. يمكنك تحديد وقت الوصول أو وقت المغادرة. في حال لم يتم تحديد أي من الوقتين، سيتم ضبط departure_time تلقائيًا على وقت التنفيذ الحالي (now). ولا يمكنك ضبط وقت الوصول والمغادرة إلا خلال الفترة الزمنية التالية، مع الإشارة إلى وقت التنفيذ الحالي (now) كمرجع: قبل now بمدة تصل إلى 7 أيام كحد أقصى لمدة تصل إلى 100 يوم تشمل كل منها بعد now يتم التعبير عن الوقت كطابع زمني بالتنسيق RFC3339 UTC "Zulu". مزيد من المعلومات
تضمين مسارات بديلة	"computeAlternativeRoutes": true	اختياريّ. اضبط القيمة على "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
          }
        },
        {},
        {},
        {},
        {},
        {},
        {}
        ]
      }
    ]
  }
]
}