الحصول على مفتاح Maps Demo Key: يمكنك تجربة ميزات محدّدة من Maps JavaScript API و"حزمة أدوات خرائط Google الجاهزة للأماكن" بدون أي تكلفة باستخدام مفتاح Maps Demo Key، وبدون الحاجة إلى إدخال معلومات الفوترة.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

خدمة Distance Matrix (الإصدار القديم)

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

ملاحظة: المكتبات من جهة الخادم

نظرة عامة

تحسب خدمة Distance Matrix من Google مسافة السفر ومدة الرحلة بين عدة نقاط انطلاق ووجهات باستخدام وسيلة نقل معيّنة.

لا تعرض هذه الخدمة معلومات تفصيلية عن المسار. يمكن الحصول على معلومات المسار، بما في ذلك الخطوط المتعدّدة والاتجاهات النصية، من خلال تمرير نقطة الانطلاق والوجهة الواحدة المطلوبة إلى خدمة الاتجاهات.

الخطوات الأولى

قبل استخدام خدمة Distance Matrix في Maps JavaScript API، تأكَّد أولاً من تفعيل Distance Matrix API (الإصدار القديم) في Google Cloud Console، في المشروع نفسه الذي أعددته لواجهة برمجة التطبيقات Maps JavaScript API.

للاطّلاع على قائمة واجهات برمجة التطبيقات المفعَّلة:

انتقِل إلى وحدة تحكّم Google Cloud.
انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة التطبيقات Maps JavaScript API وانقر على فتح.
من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Distance Matrix API (الإصدار القديم).
إذا ظهرت واجهة برمجة التطبيقات في القائمة، هذا يعني أنّه تم الانتهاء من الإعداد. إذا لم تكن واجهة برمجة التطبيقات مدرَجة، فعِّلها على الرابط https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com

الأسعار والسياسات

الأسعار

للتعرّف على سياسات الأسعار والاستخدام لخدمة Distance Matrix في JavaScript، يُرجى الاطّلاع على الاستخدام والفوترة لواجهة برمجة التطبيقات Distance Matrix API (القديمة).

ملاحظة: كل طلب يتم إرساله إلى خدمة Distance Matrix يكون محدودًا بعدد العناصر المسموح بها، حيث يحدّد عدد نقاط الانطلاق مضروبًا في عدد الوجهات عدد العناصر.

السياسات

يجب أن يكون استخدام خدمة Distance Matrix متوافقًا مع السياسات الموضّحة لواجهة برمجة التطبيقات Distance Matrix API (القديمة).

طلبات Distance Matrix

يتم الوصول إلى خدمة Distance Matrix بشكل غير متزامن، لأنّ واجهة برمجة التطبيقات Google Maps API تحتاج إلى إجراء طلب إلى خادم خارجي. لهذا السبب، عليك تمرير طريقة رد اتصال لتنفيذها عند اكتمال الطلب، وذلك لمعالجة النتائج.

يمكنك الوصول إلى خدمة Distance Matrix ضمن الرمز البرمجي من خلال عنصر الدالة الإنشائية google.maps.DistanceMatrixService. تبدأ الطريقة DistanceMatrixService.getDistanceMatrix() طلبًا إلى خدمة Distance Matrix، وتمرّر إليها كائنًا حرفيًا DistanceMatrixRequest يحتوي على نقاط الانطلاق والوجهات ووضع السفر، بالإضافة إلى طريقة رد اتصال لتنفيذها عند تلقّي الردّ.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

الاطّلاع على مثال

يحتوي DistanceMatrixRequest على الحقول التالية:

‫origins (مطلوبة): مصفوفة تحتوي على سلسلة عناوين واحدة أو أكثر، أو عناصر google.maps.LatLng، أو عناصر مكان يتم احتساب المسافة والوقت منها.
destinations (مطلوبة): مصفوفة تحتوي على سلسلة عناوين واحدة أو أكثر، أو عناصر google.maps.LatLng، أو عناصر مكان يتم احتساب المسافة والوقت إليها.
travelMode (اختيارية): وسيلة النقل التي سيتم استخدامها عند احتساب الاتجاهات. يُرجى الاطّلاع على القسم المتعلّق بوسائل النقل.
‫transitOptions (اختيارية): خيارات تنطبق فقط على الطلبات التي تكون فيها السمة travelMode هي TRANSIT. يتم وصف القيم الصالحة في القسم المتعلّق بخيارات النقل.
drivingOptions (اختياري) يحدّد القيم التي تنطبق فقط على الطلبات التي تكون فيها قيمة travelMode هي DRIVING. يتم وصف القيم الصالحة في القسم الخاص بخيارات القيادة.
unitSystem (اختيارية): نظام الوحدات الذي سيتم استخدامه عند عرض المسافة. القيم المقبولة هي:
- google.maps.UnitSystem.METRIC (تلقائي)
- google.maps.UnitSystem.IMPERIAL
‫avoidHighways (اختيارية): إذا كانت القيمة true، سيتم احتساب المسارات بين نقاط الانطلاق والوجهات لتجنّب الطرق السريعة حيثما أمكن.
‫avoidTolls (اختيارية): إذا كانت القيمة true، سيتم احتساب الاتجاهات بين النقاط باستخدام مسارات غير خاضعة لرسوم عبور، حيثما أمكن.

ملاحظة: تم إيقاف الحقل durationInTraffic نهائيًا. وكانت في السابق الطريقة المقترَحة لعملاء "الخطة المميّزة" في "منصة خرائط Google" لتحديد ما إذا كان يجب أن تتضمّن النتيجة مدة تأخذ في الاعتبار أحوال حركة المرور الحالية. يجب الآن استخدام الحقل drivingOptions بدلاً من ذلك.

أوضاع السفر

عند حساب الأوقات والمسافات، يمكنك تحديد وسيلة النقل التي تريد استخدامها. تتوفّر حاليًا وسائل النقل التالية:

‫BICYCLING يطلب اتجاهات ركوب الدراجات عبر مسارات الدراجات والشوارع المفضّلة (تتوفّر حاليًا في الولايات المتحدة وبعض المدن الكندية فقط).
DRIVING (تلقائي) يشير إلى اتجاهات القيادة العادية باستخدام شبكة الطرق.
يطلب "TRANSIT" الحصول على الاتجاهات عبر مسارات وسائل النقل العام. لا يمكن تحديد هذا الخيار إلا إذا كان الطلب يتضمّن مفتاح واجهة برمجة التطبيقات. يمكنك الاطّلاع على قسم خيارات النقل العام لمعرفة الخيارات المتاحة في هذا النوع من الطلبات.
يطلب WALKING الحصول على اتجاهات المشي عبر مسارات المشاة والأرصفة (حيثما كان ذلك متاحًا).

خيارات النقل العام

"خدمة النقل العام" هي حاليًا "تجريبية". وخلال هذه المرحلة، سنفرض حدودًا على معدّل الاستخدام لمنع إساءة استخدام واجهة برمجة التطبيقات. سنفرض في النهاية حدًا أقصى لإجمالي طلبات البحث لكل تحميل خريطة بناءً على الاستخدام العادل لواجهة برمجة التطبيقات.

تختلف الخيارات المتاحة لطلب مصفوفة المسافات حسب وسائل النقل. في طلبات النقل العام، يتم تجاهل الخيارَين avoidHighways وavoidTolls. يمكنك تحديد خيارات المسار الخاصة بالنقل العام من خلال الكائن الحرفي TransitOptions.

طلبات النقل حساسة للوقت. لن يتم عرض العمليات الحسابية إلا للأوقات المستقبلية.

يحتوي الكائن الحرفي TransitOptions على الحقول التالية:

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

في ما يلي شرح لهذه الحقول:

arrivalTime (اختيارية) تحدّد وقت الوصول المطلوب كعنصر Date. في حال تحديد وقت الوصول، يتم تجاهل وقت المغادرة.
departureTime (اختياري) يحدّد وقت المغادرة المطلوب كعنصر Date. سيتم تجاهل السمة departureTime في حال تحديد السمة arrivalTime. يتم ضبط القيمة التلقائية على الوقت الحالي إذا لم يتم تحديد قيمة لكل من departureTime أو arrivalTime.
modes (اختياري) هو مصفوفة تحتوي على كائن حرفي واحد أو أكثر من النوع TransitMode. لا يمكن تضمين هذا الحقل إلا إذا كان الطلب يتضمّن مفتاح واجهة برمجة التطبيقات. يحدّد كل عنصر TransitMode وسيلة النقل العام المفضّلة. يُسمح بالقيم التالية:
- تشير السمة BUS إلى أنّ المسار المحسوب يجب أن يفضّل السفر بالحافلة.
- تشير السمة RAIL إلى أنّ المسار المحسوب يجب أن يفضّل السفر بالقطار والترام والقطار الخفيف ومترو الأنفاق.
- تشير السمة SUBWAY إلى أنّ المسار المحسوب يجب أن يفضّل السفر عبر مترو الأنفاق.
- تشير القيمة TRAIN إلى أنّ المسار المحسوب يجب أن يفضّل السفر بالقطار.
- تشير السمة TRAM إلى أنّ المسار المحسوب يجب أن يفضّل السفر بالترام والقطار الخفيف.
routingPreference (اختيارية) تحدّد الإعدادات المفضّلة لمسارات النقل العام. باستخدام هذا الخيار، يمكنك تحسين الخيارات المعروضة، بدلاً من قبول أفضل مسار تلقائي تختاره واجهة برمجة التطبيقات. لا يمكن تحديد هذا الحقل إلا إذا كان الطلب يتضمّن مفتاح واجهة برمجة التطبيقات. يُسمح بالقيم التالية:
- FEWER_TRANSFERS تشير إلى أنّ المسار المحسوب يجب أن يفضّل عددًا محدودًا من عمليات النقل.
- LESS_WALKING تشير إلى أنّ المسار المحسوب يجب أن يفضّل المشي لمسافات محدودة.

خيارات القيادة

استخدِم العنصر drivingOptions لتحديد وقت المغادرة من أجل احتساب أفضل مسار إلى وجهتك استنادًا إلى أحوال حركة المرور المتوقّعة. يمكنك أيضًا تحديد ما إذا كنت تريد أن يكون الوقت المقدَّر في حركة المرور متشائمًا أو متفائلاً أو أفضل تقدير استنادًا إلى أحوال حركة المرور السابقة وحركة المرور المباشرة.

يحتوي عنصر drivingOptions على الحقول التالية:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

في ما يلي شرح لهذه الحقول:

departureTime (مطلوبة ليكون الكائن الحرفي drivingOptions صالحًا) تحدّد وقت المغادرة المطلوب ككائن Date. يجب ضبط القيمة على الوقت الحالي أو وقت في المستقبل. ولا يمكن أن يكون في الماضي. (تحوّل واجهة برمجة التطبيقات جميع التواريخ إلى التوقيت العالمي المنسق لضمان معالجة متسقة عبر المناطق الزمنية). إذا أدرجت departureTime في الطلب، ستعرض واجهة برمجة التطبيقات أفضل مسار استنادًا إلى أحوال حركة المرور المتوقّعة في ذلك الوقت، وستدرج الوقت المتوقّع في حركة المرور (duration_in_traffic) في الردّ. إذا لم تحدّد وقت المغادرة (أي إذا لم يتضمّن الطلب المَعلمة drivingOptions)، يكون المسار المعروض مسارًا جيدًا بشكل عام بدون أخذ أحوال حركة المرور في الاعتبار.
تنبيه: إذا لم تحدّد وقت المغادرة، يتم اختيار المسار والمدة استنادًا إلى شبكة الطرق ومتوسط أحوال حركة المرور غير المرتبطة بالوقت، وليس إلى أحوال الطرق الحالية. وبالتالي، قد تتضمّن المسارات طرقًا مغلقة مؤقتًا. قد تختلف نتائج طلب معيّن بمرور الوقت بسبب التغييرات في شبكة الطرق، وتعديل متوسط أحوال حركة المرور، والطبيعة الموزّعة للخدمة. وقد تختلف النتائج أيضًا بين المسارات المتكافئة تقريبًا في أي وقت أو معدّل تكرار.
trafficModel (اختيارية) تحدّد الافتراضات التي يجب استخدامها عند احتساب الوقت في حركة المرور. يؤثر هذا الإعداد في القيمة التي يتم عرضها في حقل duration_in_traffic في الاستجابة، والذي يحتوي على الوقت المتوقّع في حركة المرور استنادًا إلى المتوسطات السابقة. القيمة التلقائية هي best_guess. يُسمح بالقيم التالية:
- bestguess (تلقائي) يشير إلى أنّ القيمة المعروضة duration_in_traffic يجب أن تكون أفضل تقدير لمدة الرحلة استنادًا إلى ما هو معروف عن كلّ من أحوال حركة المرور السابقة وحركة المرور المباشرة. تزداد أهمية معلومات الكثافة في حركة المرور في الوقت الفعلي كلما اقترب departureTime من الوقت الحالي.
- تشير السمة pessimistic إلى أنّ قيمة duration_in_traffic التي يتم عرضها يجب أن تكون أطول من مدة الرحلة الفعلية في معظم الأيام، مع أنّ بعض الأيام التي تشهد أحوالاً سيئة بشكل خاص لحركة المرور قد تتجاوز هذه القيمة.
- تشير السمة optimistic إلى أنّ قيمة duration_in_traffic التي يتم عرضها يجب أن تكون أقصر من مدة الرحلة الفعلية في معظم الأيام، مع أنّ بعض الأيام التي تكون فيها أحوال حركة المرور جيدة بشكل خاص قد تكون أسرع من هذه القيمة.

في ما يلي نموذج DistanceMatrixRequest لمسارات القيادة، بما في ذلك وقت المغادرة ونموذج حركة المرور:

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

ردود Distance Matrix

يؤدي الطلب الناجح لخدمة Distance Matrix إلى عرض عنصر DistanceMatrixResponse وعنصر DistanceMatrixStatus. ويتم تمريرها إلى دالّة رد الاتصال التي حدّدتها في الطلب.

يحتوي العنصر DistanceMatrixResponse على معلومات المسافة والمدة لكل زوج من نقطة الانطلاق والوجهة يمكن حساب مسار له.

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

نتائج Distance Matrix

في ما يلي شرح للحقول المتوافقة في الردّ.

‫originAddresses هي مصفوفة تحتوي على المواقع الجغرافية التي تم تمريرها في حقل origins لطلب Distance Matrix. يتم عرض العناوين كما تم تنسيقها بواسطة أداة الترميز الجغرافي.
‫destinationAddresses هي مصفوفة تحتوي على المواقع الجغرافية التي تم تمريرها في الحقل destinations، بالتنسيق الذي تعرضه أداة الترميز الجغرافي.
‫rows هي مصفوفة من عناصر DistanceMatrixResponseRow، حيث يتوافق كل صف مع نقطة انطلاق.
elements هي عناصر فرعية من rows، وتتوافق مع عملية إقران نقطة انطلاق الصف بكل وجهة. وتحتوي على معلومات عن الحالة والمدة والمسافة والأجرة (إذا كانت متوفّرة) لكل زوج من نقطة الانطلاق والوجهة.
يحتوي كل element على الحقول التالية:
- status: راجِع رموز الحالة للاطّلاع على قائمة برموز الحالة المحتملة.
- ‫duration: المدة الزمنية التي يستغرقها السير في هذا المسار، ويتم التعبير عنها بالثواني (الحقل value) وtext. يتم تنسيق القيمة النصية وفقًا للسمة unitSystem المحدّدة في الطلب (أو بالنظام المتري، في حال عدم توفير أي خيار مفضّل).
- duration_in_traffic: المدة الزمنية التي يستغرقها سلوك هذا المسار مع مراعاة أحوال حركة المرور الحالية، ويتم التعبير عنها بالثواني (الحقل value) وكـ text. يتم تنسيق القيمة النصية وفقًا للسمة unitSystem المحدّدة في الطلب (أو في المقياس، في حال عدم تقديم أي خيار مفضّل). لا يتم عرض duration_in_traffic إلا في حال توفّر بيانات حركة المرور، ويتم ضبط mode على driving، ويتم تضمين departureTime كجزء من حقل distanceMatrixOptions في الطلب.
- distance: إجمالي المسافة لهذا المسار، ويتم التعبير عنها بالأمتار (value) وبصيغة text. يتم تنسيق القيمة النصية وفقًا للسمة unitSystem المحدّدة في الطلب (أو في المقياس، في حال عدم تقديم أي خيار مفضّل).
- ‫fare: يحتوي على إجمالي الأجرة (أي إجمالي تكاليف التذاكر) على هذا المسار. لا يتم عرض هذه السمة إلا لطلبات النقل العام وفقط لمقدّمي خدمات النقل العام الذين تتوفّر لديهم معلومات عن الأجرة. وتشمل هذه المعلومات ما يلي:
  - ‫currency: رمز عملة ISO 4217 يشير إلى العملة التي يتم التعبير عن المبلغ بها
  - ‫value: إجمالي مبلغ الأجرة بالعملة المحدّدة أعلاه

رموز الحالة

يتضمّن ردّ Distance Matrix رمز حالة للردّ ككل، بالإضافة إلى حالة لكل عنصر.

رموز حالة الاستجابة

يتم تمرير رموز الحالة التي تنطبق على DistanceMatrixResponse في الكائن DistanceMatrixStatus وتشمل ما يلي:

‫OK: الطلب صالح. يمكن عرض هذه الحالة حتى في حال عدم العثور على أي مسارات بين أي من نقاط الانطلاق والوجهات. يمكنك الاطّلاع على رموز حالة العناصر للحصول على معلومات الحالة على مستوى العنصر.
‫INVALID_REQUEST: الطلب المقدَّم غير صالح. ويحدث ذلك غالبًا بسبب عدم ملء الحقول المطلوبة. اطّلِع على قائمة الحقول المتوافقة أعلاه.
MAX_ELEMENTS_EXCEEDED: يتجاوز ناتج نقاط الانطلاق والوجهات الحدّ الأقصى المسموح به لكل طلب.
‫MAX_DIMENSIONS_EXCEEDED: احتوى طلبك على أكثر من 25 نقطة انطلاق أو أكثر من 25 وجهة.
‫OVER_QUERY_LIMIT: طلب تطبيقك عددًا كبيرًا جدًا من العناصر خلال الفترة الزمنية المسموح بها. من المفترض أن ينجح الطلب إذا أعدت المحاولة بعد فترة زمنية معقولة.
‫REQUEST_DENIED: رفضت الخدمة استخدام صفحة الويب لخدمة Distance Matrix.
UNKNOWN_ERROR: تعذّرت معالجة طلب Distance Matrix بسبب خطأ في الخادم. قد ينجح الطلب إذا حاولت مرة أخرى.

رموز حالة العناصر

تنطبق رموز الحالة التالية على عناصر DistanceMatrixElement معيّنة:

‫NOT_FOUND: تعذّر ترميز نقطة الانطلاق و/أو الوجهة لهذا الاقتران جغرافيًا.
‫OK: يحتوي الردّ على نتيجة صالحة.
‫ZERO_RESULTS: تعذّر العثور على مسار بين نقطة الانطلاق والوجهة.

تحليل النتائج

يحتوي العنصر DistanceMatrixResponse على عنصر row واحد لكل مصدر تم تمريره في الطلب. يحتوي كل صف على حقل element لكل عملية إقران لنقطة الانطلاق هذه مع الوجهات المقدَّمة.

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}