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-backend.googleapis.com - المصادقة: مفتاح واجهة برمجة التطبيقات
- البدء: إعداد Distance Matrix API
- المرجع: مرجع Distance Matrix API
- الأسعار: استخدام Distance Matrix API والفوترة
- السياسات: سياسات Distance Matrix 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 APIcomputeRouteMatrix(باستخدام العنوانX-Goog-FieldMask). يُرجى تفعيل واجهة برمجة التطبيقات القديمة باستخدام النموذج كإجراء قصير المدى فقط. يُرجى الاطّلاع على /maps/legacy#LegacyApiNotActivatedMapError.