خدمة مصفوفة المسافة

نظرة عامة

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

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

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

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

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

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

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

التسعير

اعتبارًا من 16 تموز (يوليو) 2018، تم اعتماد خطة تسعير جديدة لنظام "الدفع حسب الاستخدام". التأثير على الخرائط والمسارات والأماكن. لمزيد من المعلومات عن الأسعار في ما يتعلق باستخدام خدمة "مصفوفة المسافة" في JavaScript، راجِع الاستخدام والفوترة لواجهة برمجة تطبيقات مصفوفة المسافة.

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

السياسات

يجب أن يتوافق استخدام خدمة "مصفوفة المسافة" مع السياسات الموضّحة في ما يخص واجهة برمجة التطبيقات لمصفوفة المسافة

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

يُعد الوصول إلى خدمة مصفوفة المسافة غير متزامن، نظرًا لأن Google تحتاج واجهة برمجة التطبيقات للخرائط إلى إجراء اتصال بخادم خارجي. لهذا السبب، تحتاج إلى تمرير طريقة معاودة الاتصال لتنفيذها عند اكتمال في معالجة النتائج.

يمكنك الوصول إلى خدمة مصفوفة المسافة من خلال الرمز الخاص بك من خلال كائن الدالة الإنشائية 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 أو مكان الأجسام التي يجب حساب المسافة والوقت منها.
• destinations (مطلوب) - مصفوفة تحتوي على واحد أو المزيد من سلاسل العناوين أو كائنات google.maps.LatLng أو مكان الأجسام التي يجب حساب المسافة والوقت لها.
• 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. يجب أن تكون القيمة إلى الوقت الحالي أو بعض الوقت في المستقبل. لا يمكن أن تكون في في الماضي. (تحوّل واجهة برمجة التطبيقات جميع التواريخ إلى التوقيت العالمي المنسّق (UTC) لضمان معالجة متسقة عبر المناطق الزمنية). في حال تضمين 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. يتم تمريرها إلى معاودة الاتصال التي حددتها في الطلب.

يحتوي الكائن 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];
      }
    }
  }
}