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

المطوّرون في المنطقة الاقتصادية الأوروبية

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

أوجه الاختلاف بين مسارات النقل العام والمسارات الأخرى

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

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

طلب الاختلافات الاختلافات في الردود
لا يمكنك تحديد نقاط توقّف وسيطة. يتضمّن تفاصيل النقل العام.
يتعذّر الحصول على مسارات صديقة للبيئة تتضمّن البيانات الوصفية لكل وسيلة نقل تتضمّن ملخّصًا للخطوات الخاصة بوسيلة النقل هذه، وذلك في `stepsOverview` (لطلب هذه البيانات الوصفية، استخدِم قناع الحقل `routes.legs.stepsOverview`).
لا يمكن تحديد كيفية تضمين بيانات الزيارات وما إذا كان سيتم تضمينها
لا يمكن تحديد ميزات المسار التي يجب تجنُّبها
يمكن تحديد transitPreferences فقط routingPreference. للحصول على التفاصيل، يُرجى الاطّلاع على 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

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

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

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

لإجراء ذلك، استخدام هذه المَعلمة ملاحظات
اختيار وسيلة النقل العام travelMode: "TRANSIT" الحقل مطلوب. مزيد من المعلومات
ضبط وقت الوصول أو المغادرة "arrivalTime": "yyyy-mm-ddThh:mm:ssZ"

أو

"departureTime": "yyyy-mm-ddThh:mm:ssZ"		 اختيارية: يمكنك تحديد arrival_time أو departure_time. في حال عدم تحديد أي من الوقتين، سيتم ضبط القيمة التلقائية departure_time على وقت التنفيذ الحالي (now). يمكنك ضبط وقتَي الوصول والمغادرة ضمن الفترة الزمنية التالية فقط، مع استخدام وقت التنفيذ الحالي (now) كمرجع:
  • حتى 7 أيام قبل now، بما في ذلك
  • حتى 100 يوم بعد now
يتم التعبير عن الوقت كطابع زمني بتنسيق RFC3339 UTC "زولو". مزيد من المعلومات

ملاحظة: تتغيّر جداول النقل العام بشكل متكرر، وقد تتغيّر رحلات النقل العام المتاحة بمرور الوقت، ولا يمكن ضمان تقديم نتائج متسقة للتوقعات قبل وقت طويل.
تضمين مسارات بديلة "computeAlternativeRoutes": true اختيارية: اضبط القيمة على "صحيح" لكي تحسب خدمة Compute Routes ما يصل إلى 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
          }
        },
        {},
        {},
        {},
        {},
        {},
        {}
        ]
      }
    ]
  }
]
}