مرجع سريع حول Distance Matrix API

‫Distance Matrix API (الإصدار القديم) هي خدمة ويب تعرض مسافة الرحلة والوقت المستغرَق فيها لمصفوفة من نقاط الانطلاق والوجهات، استنادًا إلى المسار المقترَح بين كل زوج. يمكنك ضبط وضع السفر (القيادة أو المشي أو ركوب الدراجات أو النقل العام) وأوضاع النقل العام والوحدات ووقت المغادرة للمدد المستندة إلى حركة المرور. وتعرض هذه الواجهة ردودًا بتنسيق JSON أو XML.

‫Distance Matrix API: معلومات أساسية

  • المنتج: Distance Matrix API
  • تُعرف أيضًا باسم: Distance Matrix API (Legacy) وDistance Matrix (Legacy)
  • الفئة: المسارات
  • المنصة: خدمة ويب (REST)
  • يتم تشغيله على: الخادم (رمز الخلفية)
  • مرحلة الإطلاق: GA
  • دورة الحياة: قديمة
  • تم استبدالها بـ: Routes API
  • نظرة عامة: نظرة عامة على Distance Matrix API

‫Distance Matrix API: حالات الاستخدام

استخدِم Distance Matrix API في الحالات التالية:

  • إذا كنت تدير مشروعًا حاليًا تم فيه تفعيل Distance Matrix API (الإصدار القديم) ويطلب /maps/api/distancematrix.
  • تحتاج إلى مسافة السفر والوقت بين كل من عدة نقاط انطلاق وكل من عدة وجهات من خادم.
  • أنت بحاجة إلى مُدد في حركة المرور للقيادة، باستخدام departure_time وtraffic_model اختياري.

لا تستخدِم Distance Matrix API في الحالات التالية:

  • أنت على وشك بدء مشروع جديد على Google Cloud. اعتبارًا من أكتوبر 2026، لن يكون بالإمكان تفعيل Distance Matrix API (الإصدار القديم) للمشاريع الجديدة. استخدِم Routes API بدلاً من ذلك.
  • إذا كنت بحاجة إلى ميزات جديدة أو مصفوفة مسارات تصل إلى 625 عنصرًا مع ردود يتم بثّها (computeRouteMatrix)، استخدِم Routes API بدلاً من ذلك.
  • تحتاج إلى مسار كامل يتضمّن خطوات وخطوطًا متعدّدة بين النقاط، وليس فقط قيم المسافة والمدة. استخدِم Routes API بدلاً من ذلك.

‫Distance Matrix API: الإعداد

‫Distance Matrix API: الأخطاء الشائعة

  • المشكلة: يقتصر كل طلب من جهة الخادم على 100 عنصر (نقاط انطلاق × وجهات) وعلى 25 نقطة انطلاق أو 25 وجهة. وتعرض الطلبات الأكبر حجمًا MAX_ELEMENTS_EXCEEDED أو MAX_DIMENSIONS_EXCEEDED. الحلّ: قسِّم المصفوفة إلى طلبات لا تزيد عن 100 عنصر و25 نقطة انطلاق أو وجهة. يُرجى الاطّلاع على /maps/documentation/distance-matrix/usage-and-billing#usage-limits.
  • المشكلة: إذا لم تحدّد departure_time، يستند المسار والمدة إلى متوسط حركة المرور غير المرتبطة بالوقت، ولا يتم عرض duration_in_traffic. وقد تختلف النتائج بمرور الوقت. الحلّ: اضبط departure_time على now أو على وقت مستقبلي باستخدام mode=driving للحصول على مُدد تأخذ في الاعتبار حركة المرور. يُرجى العِلم أنّه يتم تحصيل رسوم أعلى مقابل طلبات الحصول على معلومات عن حركة المرور. يُرجى الاطّلاع على /maps/documentation/distance-matrix/distance-matrix.
  • المشكلة: لا تغيّر المَعلمة units سوى النص في حقول المسافة. تكون قيمة المسافة دائمًا بالأمتار. الحلّ: يمكنك قراءة distance.value على أنّها أمتار، أو استخدام distance.text للعرض. يُرجى الاطّلاع على /maps/documentation/distance-matrix/distance-matrix.
  • المشكلة: يؤدي طلب البيانات من Distance Matrix API (الإصدار القديم) من مشروع لم يتم تفعيلها فيه إلى عرض REQUEST_DENIED في status وerror_message يؤدي إلى LegacyApiNotActivatedMapError. غالبًا ما تنشئ المساعدات المستندة إلى الذكاء الاصطناعي رموزًا برمجية لواجهات برمجة التطبيقات القديمة تلقائيًا. الحلّ: عليك نقل البيانات إلى Routes API computeRouteMatrix (باستخدام العنوان X-Goog-FieldMask). يُرجى تفعيل واجهة برمجة التطبيقات القديمة باستخدام النموذج كإجراء قصير المدى فقط. يُرجى الاطّلاع على /maps/legacy#LegacyApiNotActivatedMapError.