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

استخدِم 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.