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

استخدِم 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]. تكون هذه المصفوفات مفهرَسة بالصفر. من المهم تخزين ترتيبات قائمة المصدر والوجهة.

أمثلة على Compute Route Matrix

استخدِم طريقة 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.