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

نظرة عامة

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

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

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

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

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

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

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

التسعير

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

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

السياسات

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

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

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