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

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

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

تختلف مسارات النقل العام التي تطلبها من خلال ضبط 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 inclusive
  • ما يصل إلى 100 يوم بما في ذلك بعد ‎now
يتم التعبير عن الوقت كطابع زمني بتنسيق RFC3339 UTC "Zulu". مزيد من المعلومات

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