نظرة عامة
تحتسب خدمة "مصفوفة المسافة" من Google مسافة السفر ومدّة الرحلة بين عدة مصادر ووجهات باستخدام وسيلة نقل معيّنة.
لا تعرض هذه الخدمة معلومات المسار التفصيلية. يمكن الحصول على معلومات المسار، بما في ذلك الخطوط المتعددة والاتجاهات النصية، من خلال تمرير المصدر الواحد المطلوب والوجهة إلى خدمة الاتجاهات.
البدء
قبل استخدام خدمة tri Matrix في Maps API API، تأكّد أولاً من تفعيل واجهة برمجة التطبيقات لمصفوفة المسافة في Google Cloud Console، وفي المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript لـ "خرائط Google".
لعرض قائمة بواجهات برمجة التطبيقات التي تم تفعيلها:
- انتقِل إلى Google Cloud Console.
- انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript لـ "خرائط Google"، ثم انقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن واجهة برمجة تطبيقات مصفوفة المسافة.
- إذا رأيت واجهة برمجة التطبيقات في القائمة، هذا يعني أنك جاهز للبدء. إذا لم تكن واجهة برمجة التطبيقات مدرَجة،
عليك تفعيلها:
- في أعلى الصفحة، انقر على تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة. بدلاً من ذلك، انقر على المكتبة في القائمة الجانبية اليمنى.
- ابحث عن واجهة برمجة التطبيقات لمصفوفة المسافة، ثم اختَرها من قائمة النتائج.
- اختَر تفعيل. عند انتهاء العملية، تظهر واجهة برمجة تطبيقات مصفوفة المسافة في قائمة واجهات برمجة التطبيقات في لوحة البيانات.
التسعير والسياسات
السعر
اعتبارًا من 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]; } } } }