هذا المنتج في الحالة القديمة. اعتبارًا من أكتوبر 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. في ما يلي قائمة بالمَعلمات والقيم المحتملة لها.

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

الوجهات

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

نقطة البداية لحساب مسافة السفر ووقته يمكنك تقديم موقع جغرافي واحد أو أكثر مفصولاً بحرف التوجيه (|)، في شكل رقم تعريف مكان أو عنوان أو إحداثيات خطوط العرض/الطول:
- رقم تعريف المكان: إذا قدّمت رقم تعريف مكان، يجب أن تسبقه بـ place_id:.
- العنوان: إذا أدخلت عنوانًا، ستعمل الخدمة على ترميز السلسلة جغرافيًا وتحويلها إلى إحداثيات خطوط العرض/الطول لاحتساب المسافة. قد تختلف هذه الإحداثيات عن تلك التي تعرضها Geocoding API، على سبيل المثال، مدخل المبنى بدلاً من وسطه.
  ملاحظة: يُفضَّل استخدام أرقام تعريف الأماكن بدلاً من العناوين أو إحداثيات خطوط العرض/الطول. سيؤدي استخدام الإحداثيات دائمًا إلى تثبيت النقطة على الطريق الأقرب إلى تلك الإحداثيات، وقد لا يكون هذا الطريق نقطة وصول إلى الموقع الجغرافي أو حتى طريقًا يؤدي بسرعة أو بأمان إلى الوجهة. سيؤدي استخدام العنوان إلى توفير المسافة إلى وسط المبنى، بدلاً من مدخل المبنى.
- الإحداثيات: إذا مرّرت إحداثيات خطوط العرض/الطول، سيتم تثبيتها على أقرب طريق. ويُفضَّل تمرير رقم تعريف المكان. إذا كنت تريد تمرير الإحداثيات، تأكَّد من عدم وجود مسافة بين قيم خطوط العرض والطول.
- يجب تنسيق رموز Plus Codes كرمز عالمي أو رمز مركّب. يجب تنسيق رموز Plus Codes كما هو موضّح هنا (يتم ترميز علامات الجمع في عنوان URL إلى ‎ %2B ويتم ترميز المسافات في عنوان URL إلى ‎ %20):
  - الرمز العالمي هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (يتم ترميز 849VCWC8+R9 إلى 849VCWC8%2BR9).
  - compound code هو رمز محلي يتألف من 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). تتطابق معظم رموز ccTLD مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق مستوى أعلى يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "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 التالي إلى بدء طلب Distance Matrix لمسافات القيادة بين بوسطن، ماساتشوستس أو تشارلزتاون، ماساتشوستس، وليكسينغتون، ماساتشوستس وكونكورد، ماساتشوستس. يتضمّن الطلب وقت المغادرة، ويستوفي جميع المتطلبات لعرض الحقل 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 إلى الشرق، وتستمر في اتجاه عقارب الساعة. على سبيل المثال، في هذا الطلب، يتّجه المسار المحسوب شرقًا من نقطة الانطلاق، ثم ينعطف إلى الخلف:

عنوان 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 مع العناوين أو أرقام تعريف الأماكن أو الخطوط المتعدّدة المرمّزة.

طلبات وردود Distance Matrix

يظهر أدناه نموذج لطلب 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 إلى أنّ الخدمة رفضت استخدام تطبيقك لخدمة Distance Matrix.
تشير السمة UNKNOWN_ERROR إلى أنّه تعذّرت معالجة طلب Distance Matrix بسبب خطأ في الخادم. قد ينجح الطلب إذا أعدت المحاولة.

DistanceMatrixRow

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

DistanceMatrixElement

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

طلبات وردود Distance Matrix

عنوان 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`