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

ملاحظة: المكتبات من جهة الخادم

نظرة عامة

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

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

البدء

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

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

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

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

السعر

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

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

السياسات

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

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

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

يمكنك الوصول إلى خدمة Distance Matrix داخل الرمز من خلال كائن المُنشئ 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. ويجب ضبط القيمة على الوقت الحالي أو على وقت ما في المستقبل. ولا يمكن أن يكون هذا التاريخ في الماضي. (تحوّل واجهة برمجة التطبيقات جميع التواريخ إلى التوقيت العالمي المتفق عليه لضمان اتّساق المناولة في جميع المناطق الزمنية.) في حال تضمين 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];
      }
    }
  }
}