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

‫Distance Matrix API هي خدمة تقبل طلب HTTPS يحتوي على نقاط الانطلاق والوجهات لطريقة نقل معيّنة. لكل منها بين نقطة الانطلاق والوجهة، فإنها تعرض مسافة السفر ومدته.

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

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

الإجراءات التي يمكنك اتّخاذها باستخدام واجهة برمجة التطبيقات لمصفوفة المسافة

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

توفّر واجهة برمجة التطبيقات لمصفوفة المسافة المعلومات استنادًا إلى المسار المقترَح بين نقطتي البداية والنهاية. يمكنك طلب هذه الأنواع من بيانات المسافة:

  • المسافة لوضع السفر الذي تم اختياره
  • المسافة بالكيلومترات أو الأميال
  • الوقت التقديري للسفر في حركة المرور

خريطة تعرض نقطة الانطلاق والوجهات على الخريطة وفي استجابة واجهة برمجة التطبيقات

آلية عمل Distance Matrix API

تستخدِم Distance Matrix API أي عدد من نقاط الانطلاق (النقاط المبدئية) والوجهات، وتُرجِع المسافة ووقت التنقّل بين كل نقطة انطلاق وجميع الوجهات المطلوبة، بدءًا من نقطة الانطلاق الأولى في الطلب ثم الانتقال بشكل تدريجي إلى النقطة التالية.

على سبيل المثال، إذا حدَّد طلبك "أ" و"ب" كأصل، و"ج" و"د" كوجهتين، سيتم عرض المسافات ووقت السفر بهذا الترتيب:

  • من أ إلى ج
  • من أ إلى د
  • ب إلى ج
  • من ب إلى ي

يوضّح المثال التالي طلبًا لمصدرَين: واشنطن العاصمة وبوسطن، ولها وجهة واحدة، وهي مدينة نيويورك، ونيويورك، في تنسيق JSON:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=New%20York%20City%2C%20NY
  &origins=Washington%2C%20DC%7CBoston
  &units=imperial
  &key=YOUR_API_KEY

الموارد

يلخص الجدول التالي الموارد المتاحة من خلال واجهة برمجة التطبيقات لمصفوفة المسافة مع البيانات التي تعرضها.

موارد البيانات البيانات التي تم عرضها تنسيق الإرجاع
مصفوفة المسافات

احرص على توفير مصادر ووجهات الأماكن في شكل معرّفات الأماكن والعناوين أو إحداثيات خطوط العرض/خطوط الطول.

  • المسافة ومدة الرحلة بين كل نقطة انطلاق وكل منها الوجهة
  • المدة التي ستستغرقها في المرور إذا حدّدت وضع القيادة و وقت المغادرة
  • JSON
  • XML

كيفية استخدام Distance Matrix API

1 بدء الإعداد ابدأ بـ إعداد مشروعك على Google Cloud وأكمِل تعليمات الإعداد التالية.
2 تجربة طلب مصفوفة المسافات بمجرد حصولك على مفتاح واجهة برمجة التطبيقات، يمكنك البدء في اختبار واجهة برمجة تطبيقات مصفوفة المسافة مباشرةً من متصفحك. يمكنك الاطّلاع على نماذج الطلبات في دليل البدء للحصول على أمثلة.
3 إنشاء طلب أكثر تعقيدًا جرِّب طلبًا يوفّر عدّة مصادر ووجهات. التعلّم حول المعلمات الاختيارية لتقييد العمليات الحسابية، مثل معلمة أو وقت المغادرة أو قيود المسار. اطّلِع على المَعلمات الاختيارية في دليل طلب مصفوفة المسافات واستجابتها.
4 فهم أساسيات الردود يمكنك استكشاف استجابات البيانات للاستعداد لاستخدام بيانات مصفوفة المسافة لتطبيقك. عرض استجابات مصفوفة المسافة لمزيد من التفاصيل.
5 دمج بيانات مصفوفة المسافات في تطبيقك يمكنك استخدام هذه البيانات لاحتساب المسافة ومدة التنقّل.

مكتبات العملاء المتاحة

يمكنك طلب بيانات من واجهة برمجة التطبيقات هذه بلغة اختيارك من خلال إحدى مكتبات العملاء التالية:

مكتبة Java Client وPython Client وGo Client وNode.js Client لخدمات "خرائط Google" هي مكتبات عملاء مفتوحة المصدر تدعمها جهات خارجية بموجب ترخيص Apache 2.0. يمكنك تنزيلها من GitHub، حيث يمكنك أيضًا العثور على تعليمات التثبيت ونماذج الرموز البرمجية.

الخطوات التالية