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

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

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

كيف تختلف مسارات النقل العام عن المسارات الأخرى؟

تختلف مسارات النقل العام، التي تطلبها من خلال ضبط 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 "Zulu"‎. مزيد من المعلومات

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