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

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

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

تختلف مسارات النقل العام التي تطلبها من خلال ضبط 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	اختياريّ. اضبط هذا الخيار على "صحيح" لحساب واجهة برمجة التطبيقات 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
          }
        },
        {},
        {},
        {},
        {},
        {},
        {}
        ]
      }
    ]
  }
]
}