هذا المنتج في الحالة القديمة. اعتبارًا من أكتوبر 2026، لن يكون بالإمكان تفعيل واجهة برمجة التطبيقات Distance Matrix API (الإصدار القديم) لمشاريع Google Cloud الجديدة. ستظل المشاريع الحالية متوافقة تمامًا. للاستفادة من الميزات الجديدة وتحسين الأداء، انتقِل إلى Routes API.

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

طلب Distance Matrix API (القديم) والاستجابة

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

مقدمة

يتّخذ طلب Distance Matrix API (الإصدار القديم) الشكل التالي:

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

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

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

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

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

الوجهات

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

نقطة البداية لاحتساب مسافة الرحلة ومدتها يمكنك تقديم موقع جغرافي واحد أو أكثر مفصولين بحرف التوجيه (|)، وذلك على شكل رقم تعريف مكان أو عنوان أو إحداثيات خطوط الطول والعرض:
- رقم تعريف المكان: إذا قدّمت رقم تعريف مكان، يجب أن تسبقه البادئة place_id:.
- العنوان: إذا أرسلت عنوانًا، ستحوّل الخدمة السلسلة إلى إحداثيات خطوط العرض والطول من أجل احتساب المسافة. قد تختلف هذه الإحداثية عن الإحداثية التي تعرضها Geocoding API، مثلاً قد تعرض مدخل مبنى بدلاً من مركزه.
  ملاحظة: يُفضّل استخدام معرّفات الأماكن على استخدام العناوين أو إحداثيات خطوط الطول والعرض. سيؤدي استخدام الإحداثيات دائمًا إلى تحديد نقطة على الطريق الأقرب إلى هذه الإحداثيات، وقد لا تكون هذه النقطة نقطة وصول إلى الموقع أو حتى طريقًا يؤدي بسرعة أو بأمان إلى الوجهة. سيؤدي استخدام العنوان إلى توفير المسافة إلى وسط المبنى، بدلاً من مدخل المبنى.
- الإحداثيات: إذا أرسلت إحداثيات خط العرض/خط الطول، سيتم محاذاتها إلى أقرب طريق. يُفضّل تمرير رقم تعريف المكان. في حال تمرير إحداثيات، تأكَّد من عدم وجود مسافة بين قيمتَي خط العرض وخط الطول.
- يجب تنسيق رموز Plus Codes كرمز عام أو رمز مركّب. يجب تنسيق رموز Plus Codes كما هو موضّح هنا (يتم تحويل علامات الجمع إلى %2B، والمسافات إلى %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، ستعود واجهة برمجة التطبيقات إلى departure_time استخدام القيمة 9999-12-31T23:59:59.999999999Z. يمكنك بدلاً من ذلك تحديد القيمة 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'

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

عنوان 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 في ردّ مصفوفة المسافات):

قيمة المَعلمة 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`	مطلوب	الرقم	قيمة رقمية

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

مقدمة

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

الوجهات

المصادر

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

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

طلب Distance Matrix API (القديم) والاستجابة

`destination_addresses`

`origin_addresses`

`rows`

`status`

`error_message`

`elements`

`status`

`distance`

`duration`

`duration_in_traffic`

`fare`

`currency`

`text`

`value`

`text`

`value`