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

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

استخدِم واجهة 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 Stream

تتلقّى طريقة 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.