خدمة Distance Matrix

المطوّرون في المنطقة الاقتصادية الأوروبية
ملاحظة: مكتبات من جهة الخادم

نظرة عامة

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

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

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

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

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

  1. انتقِل إلى وحدة تحكّم Google Cloud.
  2. انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لـ Maps JavaScript API وانقر على فتح.
  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 يحتاج إلى إجراء طلب إلى خادم خارجي. لهذا السبب، عليك تمرير طريقة callback لتنفيذها عند اكتمال الطلب، وذلك لمعالجة النتائج.

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

عند إجراء طلب ناجح إلى خدمة "مصفوفة المسافة"، يتم عرض كائن 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];
      }
    }
  }
}