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