خدمة Distance Matrix

نظرة عامة

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

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

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

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

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

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

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

الأسعار

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

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

السياسات

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

طلبات مصفوفة المسافة

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

يمكنك الوصول إلى خدمة "مصفوفة المسافات" ضمن الرمز البرمجي من خلال عنصر الإنشاء google.maps.DistanceMatrixService. يبدأ الإجراء DistanceMatrixService.getDistanceMatrix() طلبًا إلى خدمة "مصفوفة المسافات"، مع تمرير حرفي لكائن 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 أو عناصر Place التي سيتم احتساب المسافة والوقت منها.
• ‫destinations (مطلوبة) — مصفوفة تحتوي على سلسلة واحدة أو أكثر من سلاسل العناوين أو عناصر google.maps.LatLng أو عناصر Place التي سيتم احتساب المسافة والوقت إليها.
• travelMode (اختيارية) — وضع النقل الذي سيتم استخدامه عند احتساب الاتجاهات. اطّلِع على القسم الخاص بوسائل النقل.
• transitOptions (اختياري): خيارات تنطبق فقط على الطلبات التي تكون فيها قيمة travelMode هي TRANSIT. يتم توضيح القيم الصالحة في قسم خيارات النقل.
• تحدّد السمة drivingOptions (اختيارية) القيم التي تنطبق فقط على الطلبات التي تكون فيها قيمة travelMode هي DRIVING. يتم وصف القيم الصالحة في قسم خيارات القيادة.
• ‫unitSystem (اختياري): نظام الوحدات الذي سيتم استخدامه عند عرض المسافة. القيم المقبولة هي:
  • google.maps.UnitSystem.METRIC (تلقائي)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (اختيارية): إذا كانت القيمة true، سيتم احتساب المسارات بين نقاط البداية والنهاية لتجنُّب الطرق السريعة قدر الإمكان.
• avoidTolls (اختيارية): إذا كانت القيمة true، سيتم احتساب الاتجاهات بين النقاط باستخدام طرق غير خاضعة لرسوم، حيثما أمكن ذلك.

أوضاع السفر

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

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

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

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

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

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

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

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

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

• تحدّد السمة arrivalTime (اختيارية) وقت الوصول المطلوب كعنصر Date. إذا تم تحديد وقت الوصول، سيتم تجاهل وقت المغادرة.
• تحدّد السمة departureTime (اختيارية) الوقت المفضَّل للمغادرة كعنصر Date. سيتم تجاهل departureTime في حال تحديد arrivalTime. يتم ضبط القيمة التلقائية على الوقت الحالي في حال عدم تحديد قيمة لكل من departureTime أو arrivalTime.
• ‫modes (اختياري) هو صفيف يحتوي على عنصر واحد أو أكثر من عناصر TransitMode الحرفية. لا يمكن تضمين هذا الحقل إلا إذا كان الطلب يتضمّن مفتاح API. يحدّد كل TransitMode وسيلة نقل مفضّلة. يُسمح بالقيم التالية:
  • يشير BUS إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بالحافلة.
  • يشير RAIL إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بالقطار والترام والقطار الخفيف ومترو الأنفاق.
  • يشير SUBWAY إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل باستخدام مترو الأنفاق.
  • يشير TRAIN إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بالقطار.
  • يشير TRAM إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بالترام والقطار الخفيف.
• تحدّد السمة routingPreference (اختيارية) الإعدادات المفضّلة لمسارات النقل العام. باستخدام هذا الخيار، يمكنك تحديد الخيارات التي يتم عرضها بدلاً من قبول أفضل مسار تلقائي تختاره واجهة برمجة التطبيقات. لا يمكن تحديد هذا الحقل إلا إذا كان الطلب يتضمّن مفتاح API. يُسمح بالقيم التالية:
  • يشير 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

عند إجراء طلب ناجح إلى خدمة "مصفوفة المسافة"، يتم عرض كائن 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 ضمن طلب مصفوفة المسافة. يتم عرض العناوين بالتنسيق الذي يحدده برنامج الترميز الجغرافي.
• ‫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: تعذّر معالجة طلب بشأن "مصفوفة المسافات" بسبب حدوث خطأ في الخادم. قد ينجح الطلب إذا حاولت مجددًا.

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

تنطبق رموز الحالة التالية على عناصر 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];
      }
    }
  }
}