هذا المنتج أو هذه الميزة في حالة "قديم". لمزيد من المعلومات عن المرحلة القديمة وكيفية نقل البيانات من الخدمات القديمة إلى الخدمات الأحدث، يُرجى الاطّلاع على المنتجات والميزات القديمة.

طلب واستجابة واجهة برمجة التطبيقات لمصفوفة المسافات

المطوّرون في المنطقة الاقتصادية الأوروبية

مقدمة

يتّخذ طلب بيانات من واجهة برمجة التطبيقات Distance Matrix API الشكل التالي:

https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters

حيث يمكن أن تكون outputFormat إحدى القيمتين التاليتين:

يشير json (موصى به) إلى الإخراج بتنسيق JavaScript Object Notation ‏ (JSON).
يشير xml إلى الإخراج بتنسيق XML.

بعض المَعلمات مطلوبة والبعض الآخر اختياري. وكما هو معتاد في عناوين URL، يتم الفصل بين جميع المَعلمات باستخدام رمز العطف اللاتيني (&). يجب أن تكون جميع الأحرف المحجوزة (مثل علامة الجمع "+") مرمَّزة كعنوان URL. في ما يلي قائمة بالمعلمات وقيمها المحتملة.

المعلمات المطلوبة

الوجهات

موقع جغرافي واحد أو أكثر لاستخدامه كنقطة نهاية عند حساب مسافة السفر ومدته تتشابه خيارات مَعلمة الوجهات مع خيارات مَعلمة المصادر.
المصادر

تمثّل هذه السمة نقطة البداية لاحتساب مسافة الرحلة ومدتها. يمكنك تقديم موقع جغرافي واحد أو أكثر مفصولين بحرف التوجيه (|)، وذلك على شكل رقم تعريف المكان أو عنوان أو الإحداثيات:
- معرّف المكان: إذا قدّمت معرّف مكان، يجب أن تسبقه بالبادئة place_id:.
- العنوان: إذا أدخلت عنوانًا، ستحوّل الخدمة السلسلة إلى إحداثيات خطوط العرض والطول، وذلك من أجل احتساب المسافة. قد تختلف هذه الإحداثية عن الإحداثية التي تعرضها Geocoding API، مثلاً قد تعرض مدخل مبنى بدلاً من مركزه.
  ملاحظة: يُفضّل استخدام معرّفات الأماكن على استخدام العناوين أو إحداثيات خطوط الطول والعرض. سيؤدي استخدام الإحداثيات دائمًا إلى تحديد النقطة على الطريق الأقرب إلى هذه الإحداثيات، وقد لا تكون هذه النقطة نقطة وصول إلى الموقع أو حتى طريقًا يؤدي بسرعة أو بأمان إلى الوجهة. سيؤدي استخدام العنوان إلى عرض المسافة إلى وسط المبنى، وليس إلى مدخل المبنى.
- الإحداثيات: إذا مرّرت إحداثيات خط العرض/خط الطول، سيتم محاذاتها إلى أقرب طريق. يُفضّل تمرير معرّف مكان. في حال تمرير إحداثيات، تأكَّد من عدم وجود مسافة بين قيمتَي خط الطول وخط العرض.
- يجب تنسيق رموز Plus Codes كرمز عالمي أو رمز مركّب. يمكنك تنسيق رموز Plus Codes كما هو موضّح هنا (يتم تحويل علامات الجمع إلى ترميز URL باستخدام %2B، ويتم تحويل المسافات إلى ترميز URL باستخدام %20):
  - الرمز العالمي هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (يتم ترميز 849VCWC8+R9 إلى 849VCWC8%2BR9).
  - الرمز المركّب هو رمز محلي يتألف من 6 أحرف أو أكثر مع موقع جغرافي محدّد (يتم ترميز CWC8+R9 Mountain View, CA, USA إلى CWC8%2BR9%20Mountain%20View%20CA%20USA).
- الخط المتعدد الترميز بدلاً من ذلك، يمكنك تقديم مجموعة من الإحداثيات المرمّزة باستخدام خوارزمية الخط المتعدد الترميز. ويكون ذلك مفيدًا بشكل خاص إذا كان لديك عدد كبير من نقاط المصدر، لأنّ عنوان URL يكون أقصر بكثير عند استخدام خطوط متعدّدة مرمّزة.
  - يجب أن تبدأ الخطوط المتعددة المرمّزة بالبادئة enc: وأن تنتهي بنقطتَي رأسيتَين :. على سبيل المثال: origins=enc:gfo}EtohhU:
  - يمكنك أيضًا تضمين خطوط متعددة الأضلاع مشفّرة، مع الفصل بينها باستخدام الرمز العمودي |. على سبيل المثال:
```
origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
```

المعلمات الاختيارية

arrival_time

تحدّد هذه السمة الوقت المفضّل للوصول عند طلب اتجاهات النقل العام، وذلك بالثواني منذ منتصف ليل 1 يناير 1970 بالتوقيت العالمي المتفق عليه. يمكنك تحديد departure_time أو arrival_time، ولكن ليس كليهما. يجب تحديد قيمة arrival_time كعدد صحيح.
تجنُّب

يمكن احتساب المسافات التي تلتزم بقيود معيّنة. يتم الإشارة إلى القيود باستخدام المَعلمة avoid، بالإضافة إلى وسيطة لتلك المَعلمة تشير إلى القيد الذي يجب تجنُّبه. تتوفّر القيود التالية:
- يشير tolls إلى أنّ المسار المحسوب يجب أن يتجنّب الطرق/الجسور التي تتطلّب دفع رسوم عبور.
- يشير highways إلى أنّ المسار المحسوب يجب أن يتجنّب الطرق السريعة.
- يشير ferries إلى أنّ المسار المحسوب يجب أن يتجنّب العبّارات.
- يشير indoor إلى أنّ المسار المحسوب يجب أن يتجنّب الخطوات الداخلية في اتجاهات المشي والنقل العام.
يمكنك طلب مسار يتجنّب أي مجموعة من رسوم العبور والطرق السريعة والعبّارات من خلال تمرير كلا القيدين إلى المَعلمة avoid. على سبيل المثال avoid=tolls|highways|ferries.

ملاحظة: لا يؤدي إضافة قيود إلى استبعاد الطرق التي تتضمّن الميزة المحظورة، بل يؤدي إلى ترجيح النتائج لصالح الطرق الأكثر ملاءمة.
departure_time

تحدّد هذه السمة وقت المغادرة المفضّل. يمكنك تحديد الوقت كعدد صحيح بالثواني منذ منتصف ليل 1 يناير 1970 حسب التوقيت العالمي المنسق. في حال تحديد قيمة departure_time بعد 9999-12-31T23:59:59.999999999Z، ستعود واجهة برمجة التطبيقات إلى استخدام القيمة 9999-12-31T23:59:59.999999999Z.departure_time بدلاً من ذلك، يمكنك تحديد القيمة now، ما يؤدي إلى ضبط وقت المغادرة على الوقت الحالي (مع مراعاة الدقة إلى أقرب ثانية). يمكن تحديد وقت المغادرة في حالتين:
- بالنسبة إلى الطلبات التي يكون فيها وضع السفر هو النقل العام، يمكنك اختياريًا تحديد أحد الخيارين departure_time أو arrival_time. إذا لم يتم تحديد أي من الوقتين، سيتم ضبط القيمة التلقائية departure_time على الوقت الحالي (أي أنّ وقت المغادرة سيتم ضبطه تلقائيًا على الوقت الحالي).
- بالنسبة إلى الطلبات التي تكون فيها وسيلة النقل هي القيادة: يمكنك تحديد departure_time لتلقّي مسار ومدة رحلة (حقل الردّ: duration_in_traffic) يأخذان في الاعتبار أحوال حركة المرور. يجب ضبط departure_time على الوقت الحالي أو وقت في المستقبل. لا يمكن أن يكون في الماضي.
ملاحظة: في حال عدم تحديد وقت المغادرة، يستند اختيار المسار والمدة إلى شبكة الطرق ومتوسط أحوال حركة المرور غير المرتبطة بالوقت. قد تختلف نتائج طلب معيّن بمرور الوقت بسبب التغييرات في شبكة الطرق، وتعديل متوسط أحوال حركة المرور، وطبيعة الخدمة الموزّعة. قد تختلف النتائج أيضًا بين المسارات المتكافئة تقريبًا في أي وقت أو تردد.

ملاحظة: تقتصر طلبات Distance Matrix التي تحدّد departure_time عند استخدام mode=driving على 100 عنصر كحد أقصى لكل طلب. يتم تحديد عدد العناصر من خلال ضرب عدد المصادر في عدد الوجهات.
language

اللغة التي سيتم عرض النتائج بها
- اطّلِع على قائمة اللغات المتاحة. تُحدّث Google غالبًا اللغات المتوافقة، لذا قد لا تكون هذه القائمة شاملة.
- في حال عدم توفير language، تحاول واجهة برمجة التطبيقات استخدام اللغة المفضّلة كما هو محدّد في العنوان Accept-Language.
- تبذل واجهة برمجة التطبيقات قصارى جهدها لتوفير عنوان شارع يمكن قراءته من قِبل المستخدمين والسكان المحليين. لتحقيق هذا الهدف، تعرض الخدمة عناوين الشوارع باللغة المحلية، مع ترجمتها إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكونات العنوان باللغة نفسها، والتي يتم اختيارها من المكون الأول.
- إذا لم يتوفّر اسم باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابِقة.
- للغة المفضّلة تأثير بسيط على مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وعلى ترتيب عرضها. يفسّر برنامج الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة ما ولكن ليس في لغة أخرى. على سبيل المثال، utca وtér هما كلمتان مترادفتان لكلمة "شارع" باللغة الهنغارية.
الوضع

لحساب المسافات والاتجاهات، يمكنك تحديد وسيلة النقل التي تريد استخدامها. يتم استخدام الوضع DRIVING تلقائيًا. يتم تلقائيًا احتساب الاتجاهات على أنّها اتجاهات قيادة. تتوفّر وسائل النقل التالية:
- يشير الخيار driving (تلقائي) إلى اتجاهات القيادة العادية أو المسافة باستخدام شبكة الطرق.
- walking يطلب اتجاهات المشي أو المسافة باستخدام مسارات المشاة والأرصفة (حيثما توفّرت).
- bicycling يطلب اتجاهات أو مسافة ركوب الدراجات باستخدام الطرق المخصّصة للدراجات والشوارع المفضّلة (حيثما توفّرت).
- transit طلبات الاتجاهات أو المسافة باستخدام مسارات النقل العام (حيثما تتوفّر) إذا ضبطت الوضع على "نقل"، يمكنك بشكل اختياري تحديد إما departure_time أو arrival_time. إذا لم يتم تحديد أي من الوقتين، سيتم ضبط القيمة التلقائية departure_time على الوقت الحالي (أي أنّ وقت المغادرة التلقائي هو الوقت الحالي). يمكنك أيضًا تضمين transit_mode و/أو transit_routing_preference بشكل اختياري.
ملاحظة: قد لا تتضمّن اتجاهات المشي وركوب الدراجات في بعض الأحيان مسارات واضحة للمشاة أو راكبي الدراجات، لذا ستعرض هذه الاتجاهات تحذيرات في النتيجة التي يتم عرضها للمستخدم.

ملاحظة: تتوفّر رحلات النقل العام لمدة تصل إلى 7 أيام في الماضي أو 100 يوم في المستقبل، وذلك حسب توفّر معلومات النقل العام التي يقدّمها موفّرو البيانات. تتغيّر جداول النقل العام بشكل متكرّر، وقد تتغيّر رحلات النقل العام المتاحة بمرور الوقت، ولا يمكن ضمان تقديم نتائج متّسقة للتوقعات قبل وقت طويل.
المنطقة

رمز المنطقة، ويتم تحديده كقيمة من حرفين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD). تتطابق معظم رموز نطاقات المستوى الأعلى لرمز البلد مع رموز ISO 3166-1، مع بعض الاستثناءات البارزة. على سبيل المثال، نطاق المستوى الأعلى لرمز البلد في المملكة المتحدة هو "uk" (.co.uk)، بينما رمز ISO 3166-1 هو "gb" (وهو يشير تقنيًا إلى الكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").
traffic_model

تحدّد هذه السمة الافتراضات التي يجب استخدامها عند احتساب الوقت المستغرَق في حركة المرور. يؤثر هذا الخيار في القيمة المعروضة في الحقل duration_in_traffic ضمن الاستجابة، والذي يتضمّن الوقت المتوقّع في حركة المرور استنادًا إلى المعدّلات السابقة. لا يمكن تحديد المَعلمة traffic_model إلا لاتجاهات القيادة التي يتضمّن الطلب فيها departure_time. القيم المتاحة لهذه المَعلمة هي:
- تشير best_guess (القيمة التلقائية) إلى أنّ duration_in_traffic المعروضة يجب أن تكون أفضل تقدير لمدة الرحلة استنادًا إلى المعلومات المتوفّرة عن كلّ من حالة حركة المرور السابقة وحركة المرور الحالية. تزداد أهمية بيانات حركة المرور المباشرة كلما اقترب وقت departure_time من الوقت الحالي.
- يشير pessimistic إلى أنّ المدة المعروضة في duration_in_traffic يجب أن تكون أطول من مدة الرحلة الفعلية في معظم الأيام، على الرغم من أنّ بعض الأيام التي تكون فيها أحوال حركة المرور سيئة بشكل خاص قد تتجاوز هذه القيمة.
- يشير optimistic إلى أنّ مدة السفر التي يتم عرضها في السمة duration_in_traffic يجب أن تكون أقصر من مدة السفر الفعلية في معظم الأيام، مع العلم أنّ بعض الأيام التي تكون فيها حالة حركة المرور جيدة جدًا قد تكون أسرع من هذه القيمة.
ستوفّر القيمة التلقائية لـ best_guess التوقّعات الأكثر فائدة لمعظم حالات الاستخدام. من المحتمل أن تكون best_guess مدة الرحلة المتوقّعة أقصر من optimistic، أو أطول من pessimistic، وذلك بسبب الطريقة التي يدمج بها نموذج التوقّع best_guess معلومات حركة المرور المباشرة.
transit_mode

تحدّد هذه السمة وسيلة نقل عام مفضّلة واحدة أو أكثر. لا يمكن تحديد هذه المَعلمة إلا لاتجاهات النقل العام. تتيح المَعلمة الوسيطات التالية:
- يشير bus إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بالحافلة.
- يشير الرمز subway إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بواسطة مترو الأنفاق.
- يشير train إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بالقطار.
- يشير tram إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بالترام والقطار الخفيف.
- يشير rail إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل بالقطار والترام والقطار الخفيف ومترو الأنفاق. وهذا يعادل transit_mode=train|tram|subway.
transit_routing_preference

تحدّد هذه السمة الإعدادات المفضّلة لمسارات النقل العام. باستخدام هذه المَعلمة، يمكنك تحديد الخيارات التي يتم عرضها بدلاً من قبول أفضل مسار تلقائي تختاره واجهة برمجة التطبيقات. لا يمكن تحديد هذه المَعلمة إلا لاتجاهات النقل العام. تتيح المَعلمة الوسيطات التالية:
- يشير الرمز less_walking إلى أنّ المسار المحسوب يجب أن يفضّل السير لمسافات محدودة.
- يشير fewer_transfers إلى أنّ المسار المحسوب يجب أن يفضّل عددًا محدودًا من عمليات النقل.
وحدة

تحدّد هذه السمة نظام الوحدات الذي سيتم استخدامه عند عرض النتائج.

ملاحظة: يؤثر إعداد نظام الوحدات هذا فقط في النص المعروض ضمن حقول المسافة. تحتوي حقول المسافة أيضًا على قيم يتم التعبير عنها دائمًا بالمتر.

أمثلة على الطلبات

يستخدم هذا المثال إحداثيات خطوط الطول والعرض لتحديد إحداثيات الوجهة:

عنوان URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

يستخدم هذا المثال رموز Plus Codes لتحديد إحداثيات الوجهة:

عنوان URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

يعرض هذا المثال الطلب نفسه باستخدام خط متعدد الأضلاع مرمّز:

عنوان URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

معلومات حركة المرور

يتم استخدام معلومات حركة المرور عندما تنطبق جميع الشروط التالية (هذه هي الشروط المطلوبة لتلقّي الحقل duration_in_traffic في استجابة Distance Matrix):

تكون المَعلمة mode الخاصة بالسفرdriving أو لم يتم تحديدها (driving هو وضع السفر التلقائي).
يتضمّن الطلب المَعلمة departure_time الصالحة. يمكن ضبط departure_time على الوقت الحالي أو على وقت في المستقبل. لا يمكن أن يكون في الماضي.

يمكنك اختياريًا تضمين المَعلمة traffic_model في طلبك لتحديد الافتراضات التي سيتم استخدامها عند احتساب الوقت المستغرَق في حركة المرور.

يبدأ عنوان URL التالي طلبًا للحصول على "مصفوفة المسافات" من أجل حساب مسافات القيادة بين بوسطن أو تشارلزتاون في ماساتشوستس، وبين ليكسينغتون أو كونكورد في ماساتشوستس. يتضمّن الطلب وقت المغادرة، ويستوفي جميع المتطلبات لعرض الحقل duration_in_traffic في استجابة Distance Matrix.

عنوان URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

JSON

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins

معدِّلات المواقع الجغرافية

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

تحديد أنّ المسارات المحسوبة يجب أن تمرّ بجانب معيّن من الطريق

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

عنوان URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

عند استخدام side_of_road: مع خطوط متعدّدة الأضلاع مشفّرة، يتم تطبيق المعدِّل على كل موقع جغرافي على طول الخط المتعدّد الأضلاع. على سبيل المثال، تستخدم الوجهتان في هذا الطلب المَعلمة نفسها:

عنوان URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

لا يمكن استخدام المعدِّل side_of_road: إلا مع القيد التالي:

قيمة المَعلمة mode الخاصة بالسفر هي driving، أو لم يتم تحديدها (driving هو وضع السفر التلقائي).

تحديد أنّ المسارات المحسوبة يجب أن تتضمّن عنوانًا معيّنًا

عند تحديد موقع جغرافي، يمكنك طلب أن يمر المسار المحسوب بالموقع الجغرافي في اتجاه معيّن. يتم تحديد هذا العنوان باستخدام البادئة heading=X:، حيث يمثّل X قيمة عددية صحيحة بالدرجات تتراوح بين 0 (شامل) و360 (غير شامل). يشير العنوان 0 إلى الشمال، و90 إلى الشرق، ويستمر في اتجاه عقارب الساعة. على سبيل المثال، في هذا الطلب، يتّجه المسار المحسوب شرقًا من نقطة البداية، ثم ينعطف على شكل حرف U:

عنوان URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

لا يمكن استخدام المعدِّل heading=X: إلا مع القيود التالية:

تكون قيمة المَعلمة mode الخاصة بالسفرdriving أو bicycling أو غير محدّدة (driving هي وسيلة النقل التلقائية).
لم يتم تحديد معدِّل side_of_road للموقع الجغرافي نفسه.
يتم تحديد الموقع الجغرافي باستخدام قيمة خط العرض/خط الطول. لا يمكنك استخدام heading مع العناوين أو معرّفات الأماكن أو الخطوط المتعددة المرمّزة.

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

يظهر أدناه نموذج لطلب HTTP يطلب المسافة والمدة من فانكوفر، كولومبيا البريطانية، كندا ومن سياتل، واشنطن، الولايات المتحدة الأمريكية إلى سان فرانسيسكو، كاليفورنيا، الولايات المتحدة الأمريكية وإلى فيكتوريا، كولومبيا البريطانية، كندا.

عنوان URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco%7CVictoria%20BC
  &language=fr-FR
  &mode=bicycling
  &origins=Vancouver%20BC%7CSeattle
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'

سيعرض هذا الطلب أربعة عناصر، أي موقعَين جغرافيَين مضروبَين في وجهتَين:

من فانكوفر إلى سان فرانسيسكو	من فانكوفر إلى فيكتوريا
من سياتل إلى سان فرانسيسكو	سياتل إلى فيكتوريا

يتم عرض النتائج في صفوف، ويحتوي كل صف على مصدر واحد مقترن بكل وجهة.

JSON

{
  "destination_addresses":
    ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"],
  "origin_addresses":
    ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "1 712 km", "value": 1711765 },
              "duration": { "text": "3 jours 16 heures", "value": 318119 },
              "status": "OK",
            },
            {
              "distance": { "text": "140 km", "value": 139695 },
              "duration": { "text": "6 heures 49 minutes", "value": 24567 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "1 452 km", "value": 1451704 },
              "duration": { "text": "3 jours 2 heures", "value": 266680 },
              "status": "OK",
            },
            {
              "distance": { "text": "146 km", "value": 146500 },
              "duration": { "text": "2 heures 53 minutes", "value": 10374 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km

DistanceMatrixResponse

الحقل	مطلوب	النوع	الوصف
`destination_addresses`	مطلوب	Array<string>	مصفوفة من العناوين التي تعرضها واجهة برمجة التطبيقات استجابةً لطلبك الأصلي. وكما هو الحال مع `origin_addresses`، يتم تعديل هذه القيم لتناسب اللغة المحلية عند الاقتضاء. يجب قراءة هذا المحتوى كما هو، ويُرجى عدم تحليل العناوين المنسَّقة آليًا.
`origin_addresses`	مطلوب	Array<string>	مصفوفة من العناوين التي تعرضها واجهة برمجة التطبيقات استجابةً لطلبك الأصلي. ويتم تنسيقها بواسطة أداة الترميز الجغرافي وتتم أقلمتها وفقًا لمعلَمة اللغة التي يتم تمريرها مع الطلب. يجب قراءة هذا المحتوى كما هو، ويُرجى عدم تحليل العناوين المنسَّقة آليًا.
`rows`	مطلوب	Array<DistanceMatrixRow>	تمثّل هذه السمة مصفوفة من العناصر، يحتوي كل منها بدوره على عناصر `status` و`duration` و`distance`. يمكنك الاطّلاع على DistanceMatrixRow لمزيد من المعلومات.
`status`	مطلوب	DistanceMatrixStatus	يحتوي على حالة الطلب، وقد يتضمّن معلومات تصحيح الأخطاء لمساعدتك في معرفة سبب تعذُّر تلبية الطلب. لمزيد من المعلومات، يُرجى الاطّلاع على DistanceMatrixStatus.
`error_message`	اختياري	سلسلة	سلسلة تحتوي على نص يمكن لشخص عادي قراءتها يتضمّن أي أخطاء تمت مواجهتها أثناء معالجة الطلب.

DistanceMatrixStatus

رموز الحالة التي تعرضها الخدمة

يشير OK إلى أنّ الردّ يحتوي على نتيجة صالحة.
يشير الرمز INVALID_REQUEST إلى أنّ الطلب المقدَّم غير صالح.
يشير MAX_ELEMENTS_EXCEEDED إلى أنّ عدد المنتجات من المصادر والوجهات يتجاوز الحدّ الأقصى المسموح به لكل طلب بحث.
يشير MAX_DIMENSIONS_EXCEEDED إلى أنّ عدد نقاط الأصل أو الوجهات يتجاوز الحدّ الأقصى المسموح به لكل طلب بحث.
يشير OVER_DAILY_LIMIT إلى أي مما يلي:
- مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح.
- لم يتم تفعيل الفوترة في حسابك.
- تم تجاوز الحد الأقصى للاستخدام الذي تم فرضه ذاتيًا.
- لم تعُد طريقة الدفع المقدَّمة صالحة (على سبيل المثال، انتهت صلاحية بطاقة ائتمان).
يشير الرمز OVER_QUERY_LIMIT إلى أنّ الخدمة تلقّت عددًا كبيرًا جدًا من الطلبات من تطبيقك خلال الفترة الزمنية المسموح بها.
يشير الرمز REQUEST_DENIED إلى أنّ الخدمة رفضت استخدام تطبيقك لخدمة "مصفوفة المسافات".
يشير الرمز UNKNOWN_ERROR إلى تعذُّر معالجة طلب بشأن "مصفوفة المسافات" بسبب حدوث خطأ في الخادم. قد ينجح الطلب إذا أعدت المحاولة.

DistanceMatrixRow

الحقل	مطلوب	النوع	الوصف
`elements`	مطلوب	Array<DistanceMatrixElement>	عندما تعرض واجهة برمجة التطبيقات Distance Matrix API النتائج، تضعها ضمن مصفوفة صفوف JSON. حتى إذا لم يتم عرض أي نتائج (مثلما يحدث عندما لا تكون المصادر و/أو الوجهات متوفّرة)، سيتم عرض مصفوفة فارغة. يتم ترتيب الصفوف وفقًا للقيم في المَعلمة origin الخاصة بالطلب. يتطابق كل صف مع مصدر، ويتطابق كل عنصر ضمن هذا الصف مع عملية ربط بين المصدر وقيمة وجهة. تحتوي كل مصفوفة صف على إدخال واحد أو أكثر من إدخالات العناصر، والتي بدورها تحتوي على معلومات حول زوج واحد من المصدر والوجهة. لمزيد من المعلومات، يُرجى الاطّلاع على DistanceMatrixElement.

DistanceMatrixElement

الحقل	مطلوب	النوع	الوصف
`status`	مطلوب	DistanceMatrixElementStatus	تمثّل هذه السمة حالة العنصر. لمزيد من المعلومات، يمكنك الاطّلاع على DistanceMatrixElementStatus.
`distance`	اختياري	TextValueObject	إجمالي مسافة هذا المسار، معبّرًا عنها بالمتر (القيمة) وك نص. تستخدِم القيمة النصية نظام الوحدات المحدّد باستخدام مَعلمة الوحدة في الطلب الأصلي، أو منطقة المصدر. لمزيد من المعلومات، يمكنك الاطّلاع على TextValueObject.
`duration`	اختياري	TextValueObject	تمثّل هذه السمة المدة الزمنية المستغرقة في قطع هذه المسافة، ويتم التعبير عنها بالثواني (حقل القيمة) وكوصف نصي. يتم توفير التمثيل النصي وفقًا لمعلَمة اللغة الخاصة بطلب البحث. لمزيد من المعلومات، يمكنك الاطّلاع على TextValueObject.
`duration_in_traffic`	اختياري	TextValueObject	هي المدة الزمنية التي يستغرقها التنقّل في هذا المسار، استنادًا إلى أحوال حركة المرور الحالية والسابقة. راجِع مَعلمة الطلب `traffic_model` للاطّلاع على الخيارات التي يمكنك استخدامها لطلب أن تكون القيمة المعروضة متفائلة أو متشائمة أو تقديرًا بأفضل تخمين. يتم التعبير عن المدة بالثواني (حقل القيمة) وكنص. يتم توطين التمثيل النصي وفقًا لمعلَمة اللغة الخاصة بطلب البحث. لا يتم عرض المدة في حركة المرور إلا إذا استوفيت جميع الشروط التالية: يتضمّن الطلب المَعلمة `departure_time`. تتوفّر معلومات عن أحوال حركة المرور للمسار المطلوب. تم ضبط مَعلمة الوضع على "القيادة". لمزيد من المعلومات، يمكنك الاطّلاع على TextValueObject.
`fare`	اختياري	الأجرة	في حال توفّره، يحتوي على إجمالي الأجرة (أي إجمالي تكاليف التذكرة) على هذا المسار. لا يتم عرض هذه السمة إلا لطلبات النقل العام، وفقط لمزوّدي خدمات النقل العام الذين تتوفّر لديهم معلومات عن الأسعار. يُرجى الاطّلاع على الأجرة لمزيد من المعلومات.

السعر

تمثّل هذه السمة إجمالي الأجرة للمسار.

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}

الحقل	مطلوب	النوع	الوصف
`currency`	مطلوب	سلسلة	تمثّل هذه السمة رمز العملة بتنسيق ISO 4217 الذي يشير إلى العملة التي يتم التعبير عن المبلغ بها.
`text`	مطلوب	سلسلة	مبلغ الأجرة الإجمالي، منسَّقًا باللغة المطلوبة
`value`	مطلوب	الرقم	إجمالي مبلغ الأجرة بالعملة المحدّدة

DistanceMatrixElementStatus

يشير OK إلى أنّ الردّ يحتوي على نتيجة صالحة.
يشير الرمز NOT_FOUND إلى أنّه تعذّر الترميز الجغرافي لنقطة الانطلاق و/أو الوجهة في عملية الربط هذه.
يشير الرمز ZERO_RESULTS إلى أنّه لم يتم العثور على أي مسار بين نقطة الانطلاق والوجهة.
يشير الرمز MAX_ROUTE_LENGTH_EXCEEDED إلى أنّ المسار المطلوب طويل جدًا ولا يمكن معالجته.

TextValueObject

عنصر يحتوي على قيمة رقمية وتمثيل نصي منسَّق لها.

الحقل	مطلوب	النوع	الوصف
`text`	مطلوب	سلسلة	قيمة السلسلة
`value`	مطلوب	الرقم	قيمة رقمية

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

مقدمة

المعلمات المطلوبة

الوجهات

المصادر

المعلمات الاختيارية

arrival_time

تجنُّب

departure_time

language

الوضع

المنطقة

traffic_model

transit_mode

transit_routing_preference

وحدة

أمثلة على الطلبات

عنوان URL

curl

عنوان URL

curl

عنوان URL

curl

معلومات حركة المرور

عنوان URL

curl

JSON

XML

معدِّلات المواقع الجغرافية

تحديد أنّ المسارات المحسوبة يجب أن تمرّ بجانب معيّن من الطريق

عنوان URL

curl

عنوان URL

curl

تحديد أنّ المسارات المحسوبة يجب أن تتضمّن عنوانًا معيّنًا

عنوان URL

curl

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

عنوان URL

curl

JSON

XML

DistanceMatrixResponse

destination_addresses

origin_addresses

rows

status

error_message

DistanceMatrixStatus

DistanceMatrixRow

elements

DistanceMatrixElement

status

distance

duration

duration_in_traffic

fare

السعر

currency

text

value

DistanceMatrixElementStatus

TextValueObject

text

value

طلب واستجابة واجهة برمجة التطبيقات لمصفوفة المسافات

`destination_addresses`

`origin_addresses`

`rows`

`status`

`error_message`

`elements`

`status`

`distance`

`duration`

`duration_in_traffic`

`fare`

`currency`

`text`

`value`

`text`

`value`