الحصول على مصفوفة مسار

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

استخدِم Routes API لاحتساب مسافة ومدة مسار لعدة نقاط بداية ووجهات من خلال استدعاء طريقة computeRouteMatrix (REST) أو طريقة البث ComputeRouteMatrix (gRPC).

عند توفير قائمة بالمصادر والوجهات، تحسب الطريقة المسافة ومدة المسار بدءًا من كل مصدر وانتهاءً بكل وجهة.

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

يمكنك أيضًا احتساب مصفوفة طرق النقل العام. للاطّلاع على مثال، راجِع الحصول على مصفوفة مسارات في وسائل النقل العام.

الحدود القصوى المسموح بها للطلبات

تفرض طرق Compute Route Matrix حدود الطلبات التالية لنقاط الطريق باستخدام العناوين أو معرّفات الأماكن، وللعناصر. العناصر هي الطرق بين كل نقطة انطلاق ووجهة في مصفوفة الطرق، وبالتالي فإنّ عدد العناصر هو عدد نقاط الانطلاق مضروبًا في عدد الوجهات. على سبيل المثال، إذا كان لديك 10 مواقع أصلية و10 وجهات، سيكون لديك 100 عنصر:

  • يجب ألا يتجاوز عدد العناصر 625 للطرق التي لا تكون طرق TRANSIT.

  • في حال تحديد TRANSIT مسار، لا يمكن أن يتجاوز عدد العناصر 100.

  • في حال تحديد TRAFFIC_AWARE_OPTIMAL، يجب ألا يتجاوز عدد العناصر 100. لمزيد من المعلومات حول TRAFFIC_AWARE_OPTIMAL، يُرجى الاطّلاع على تحديد كيفية تضمين بيانات حركة المرور وما إذا كان يجب تضمينها.

  • إذا حدّدت المصادر أو الوجهات باستخدام عنوان أو رقم تعريف مكان، يمكنك تحديد ما يصل إلى 50 إجماليًا بهذه الطريقة.

أخطاء الاستجابة

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

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

نتائج بث gRPC

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

لا نضمن ترتيب العناصر التي يعرضها البث. لذلك، يحتوي كل عنصر ردّ على origin_index وdestination_index. بالنسبة إلى نقاط الانطلاق والوجهات المحدّدة في الطلب، تكون نقطة انطلاق المسار مكافئة origins[origin_index] لعنصر معيّن، وتكون وجهة المسار مكافئة destinations[destination_index]. هذه المصفوفات مفهرسة من الصفر. من المهم تخزين ترتيبات قوائم المصدر والوجهة.

أمثلة على احتساب مصفوفة طرق

استخدِم طريقة computeRouteMatrix في طلب HTTP لاحتساب مصفوفة طرق.

مثال على HTTP

يوضّح المثال التالي طلب HTTP computeRouteMatrix. في هذا المثال، يمكنك إجراء ما يلي:

  • حدِّد مصفوفة تتضمّن نقطتَي طريق للمصدر ونقطتَي طريق للوجهة. تحسب الطريقة مسارًا من كل نقطة انطلاق إلى كل وجهة، وبالتالي يحتوي الردّ على أربعة مسارات.

    في المصفوفة، يكون العنصر الأول في الفهرس 0، والثاني في الفهرس 1، وهكذا.

  • تضمين قناع حقل الرد لتحديد الحقول المطلوب عرضها من الرد (REST) أو ComputeRoutesResponse (gRPC). في هذا المثال، اضبط الطلب لعرض originIndex وdestinationIndex وduration وdistanceMeters وstatus وcondition لكل مسار. لمزيد من المعلومات، يُرجى الاطّلاع على اختيار الحقول التي سيتم عرضها.

curl -X POST -d '{
  "origins": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420761,
            "longitude": -122.081356
          }
        }
      },
      "routeModifiers": { "avoid_ferries": true}
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.403184,
            "longitude": -122.097371
          }
        }
      },
      "routeModifiers": { "avoid_ferries": true}
    }
  ],
  "destinations": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420999,
            "longitude": -122.086894
          }
        }
      }
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.383047,
            "longitude": -122.044651
          }
        }
      }
    }
  ],
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status,condition' \
'https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix'

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

حدِّد كل مسار في الرد باستخدام حقلَي الرد originIndex وdestinationIndex. على سبيل المثال، يشير originIndex بقيمة 1 في الرد إلى مسار تم احتسابه من نقطة الطريق في الفهرس 1 من مصفوفة origins في الطلب.

[
    {
        "originIndex": 0,
        "destinationIndex": 0,
        "status": {},
        "distanceMeters": 822,
        "duration": "160s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 1,
        "destinationIndex": 0,
        "status": {},
        "distanceMeters": 2919,
        "duration": "361s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 1,
        "destinationIndex": 1,
        "status": {},
        "distanceMeters": 5598,
        "duration": "402s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 0,
        "destinationIndex": 1,
        "status": {},
        "distanceMeters": 7259,
        "duration": "712s",
        "condition": "ROUTE_EXISTS"
    }
]

أمثلة على gRPC

على سبيل المثال، بالنسبة إلى طلبات gRPC، يمكنك الاطّلاع على الأمثلة في مثال على طلب gRPC. يستدعي مثال Java في تلك الصفحة كلاً من Compute Routes وCompute Route Matrix.