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

نظرة عامة

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

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

البدء

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

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

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

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

السعر

اعتبارًا من 16 تموز (يوليو) 2018، دخلت خطة التسعير الجديدة "الدفع حسب الاستخدام" حيز التنفيذ في "خرائط Google" و"المسارات" و"الأماكن". لمعرفة المزيد من المعلومات حول الأسعار الجديدة وحدود الاستخدام لاستخدام خدمة مصفوفة المسافات في 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 أو عناصر 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. ويتم تمرير هذه البيانات إلى دالة معاودة الاتصال التي حدّدتها في الطلب.

يحتوي الكائن 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 فقط لعملاء الخطة المميزة في "منصة خرائط Google" حيث تتوفر بيانات حركة المرور، ويتم ضبط 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];
      }
    }
  }
}