خدمة Distance Matrix

نظرة عامة

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

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

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

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

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

1. انتقِل إلى Google Cloud Console.
2. انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لمكتبة Maps JavaScript API، ثم انقر على فتح.
3. من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Distance Matrix API.
4. إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك قد أكملت الخطوات اللازمة. إذا لم تكن واجهة برمجة التطبيقات مُدرَجة، فعِّلها:
   1. في أعلى الصفحة، انقر على تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة. بدلاً من ذلك، انقر على المكتبة من القائمة اليمنى.
   2. ابحث عن Distance Matrix API، ثم اختَره من قائمة النتائج.
   3. انقر على تفعيل. عند اكتمال العملية، تظهر Distance Matrix API في قائمة واجهات برمجة التطبيقات في لوحة البيانات.

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

التسعير

اعتبارًا من 16 تموز (يوليو) 2018، بدأ تطبيق خطة أسعار جديدة "الدفع حسب الاستخدام" في "خرائط Google" و"الطرق" و"الأماكن". للاطّلاع على مزيد من المعلومات عن الأسعار الجديدة وحدود الاستخدام الجديدة لاستخدامك لخدمة Distance Matrix JavaScript، يُرجى الاطّلاع على الاستخدام والفوترة لـ Distance Matrix API.

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

السياسات

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

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

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

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

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

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

يحتوي عنصر 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"
      }
    } ]
  } ]
}

نتائج "مصفوفة المسافات"

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

• 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: إجمالي مبلغ الأجرة، بالعملة المحدّدة أعلاه

رموز الحالة

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

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

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

• OK — الطلب صالح. يمكن عرض هذه الحالة حتى إذا لم يتم العثور على أي مسارات بين أي من نقاط المغادرة والوصول. اطّلِع على رموز حالة العناصر للحصول على معلومات الحالة على مستوى العنصر.
• INVALID_REQUEST — كان الطلب المقدَّم غير صالح. ويحدث ذلك غالبًا بسبب عدم توفّر الحقول المطلوبة. اطّلِع على قائمة الحقول المتوافقة أعلاه.
• MAX_ELEMENTS_EXCEEDED - يتجاوز حاصل الأصول والوجهات الحدّ الأقصى لكلّ طلب بحث.
• MAX_DIMENSIONS_EXCEEDED - يتضمّن طلبك أكثر من 25 نقطة انطلاق أو أكثر 25 وجهة.
• OVER_QUERY_LIMIT - طلب تطبيقك عددًا كبيرًا جدًا من العناصر خلال الفترة الزمنية المسموح بها. من المفترض أن يتم تنفيذ الطلب إذا حاولت مرة أخرى بعد فترة معقولة من الوقت.
• REQUEST_DENIED - رفضت الخدمة استخدام خدمة "مصفوفة المسافات" من قِبل صفحة الويب.
• 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];
      }
    }
  }
}