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