نظرة عامة على Routes API

‫Routes API هي خدمة تقبل طلب HTTPS وتُعيد إما المسار المثالي بين موقعَين جغرافيَّين أو المسافات ووقت التنقّل لمصفّحة من المسارات بين مواقع جغرافية مختلفة للمصدر والوجهة.

سبب استخدام Routes API

باستخدام Routes API، يمكنك الحصول على مسارات ومعلومات رحلة دقيقة باستخدام تفاصيل وسائل النقل وأحدث المعلومات عن حركة المرور وحالة الطرق وإعدادات المسار المفضّلة:

  • نوع وسائل النقل المختلفة وإمكاناتها

  • الاتجاه الذي تسير فيه المركبة

  • جانب الطريق لعمليات الاستلام أو الإرجاع

  • أحوال حركة المرور وإغلاق الطرق

  • المخاوف المتعلقة بالسلامة، مثل تجنُّب المناطق الخطيرة أو توفير مناطق 픽 up آمنة

  • موازنة وقت الاستجابة والجودة والتكلفة في جميع احتياجات التوجيه باستخدام ميزات اختيارية، مثل الرسوم والبيانات الوصفية للرحلة، مثل الوقت والمسافة وكفاءة الوقود

يمكنك أيضًا تحديد المسارات الأكثر فعالية لجدولة عمليات الإرسال، مثل:

  • أفضل طريقة لتعيين مجموعة من العمال لجمع سلسلة من الطرود

  • تحديد أفضل مستودع لشحن الطرود إلى وجهتها النهائية

ما هي الإجراءات التي يمكنك اتّخاذها باستخدام Routes API؟

باستخدام Routes API، يمكنك الحصول على فئتين أساسيتَين من معلومات التوجيه:

  • المسارات من موقع جغرافي إلى وجهة واحدة أو متعددة

  • مصفوفة للمسارات المحتملة بين العديد من المواقع الجغرافية لنقاط البدء والانتهاء

الحصول على مسارات لوجهة واحدة أو متعددة

باستخدام طريقة Compute Routes في Routes API، يمكنك احتساب المسافة بين المواقع الجغرافية:

  • الحصول على اتجاهات لطرق سفر مختلفة ووجهات واحدة أو متعددة:

    • وسائل النقل، بما في ذلك وسائل النقل العام والقيادة والمركبات ذات العجلتين والمشي أو ركوب الدراجات

    • سلسلة من نقاط الطريق التي يمكنك تحسينها لتحديد الترتيب الأكثر فعالية للتنقّل بينها

  • طرق متعدّدة لتحديد الأصول والوجهات ونقاط المسار:

    • سلاسل نصية على سبيل المثال: "القاهرة، مصر" أو "الإسكندرية، مصر" أو "1800 Amphitheatre Parkway, Mountain View, CA 94043" أو "CWF6+FWX Mountain View, California"

    • أرقام تعريف الأماكن

    • إحداثيات خط العرض وخط الطول، مع الاتجاه المقصود للمركبة اختياريًا

  • تحسين خيارات المسار استنادًا إلى احتياجاتك وأهدافك:

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

الحصول على مصفوفة من المسارات المحتملة

توفّر طريقة Compute Route Matrix في Routes API جدولاً متسلسلاً من المعلومات عن المسارات المقترَحة بين نقاط بداية وانتهاء متعددة، بما في ذلك المسافة وأوقات الوصول المقدَّرة، لمساعدتك في اختيار أفضل نقاط الانطلاق والوجهة استنادًا إلى احتياجات نشاطك التجاري. يمكنك طلب الأنواع التالية من بيانات المسافة:

  • المسافة لطريقة سفر محدّدة

  • المسافة بالكيلومترات أو الأميال

  • الوقت المقدَّر للسفر في ساعة الذروة

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

يمكنك بث عناصر من الاستجابة قبل حساب المصفوفة بالكامل، ما يقلل من وقت استجابة البث.

يمكنك تحديد مصادر ووجهات متعددة لكل طلب من جانب الخادم مع عدد المصادر مضروبًا في عدد الوجهات بما يصل إلى 625.

آلية عمل Routes API

تتضمّن Routes API طريقتَين: ComputeRoutes و ComputeRouteMatrix.

ComputeRoutes

تقبل طريقة ComputeRoutes في Routes API طلب HTTP POST مع نص طلب JSON يحتوي على تفاصيل الطلب. يجب توفير نقطة الانطلاق ونقطة الوصول ووضع التنقّل وقناع حقل لتحديد الحقول التي سيتم عرضها.

مثال

curl -X POST -d '{
    "origin": {
      "address": "1800 Amphitheatre Parkway, Mountain View, CA 94043"
    },
    "destination": {
      "address": "Sloat Blvd &, Upper Great Hwy, San Francisco, CA 94132"
    },
  "travelMode": "DRIVE"
  }' \
  -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
  -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters' \
  'https://routes.googleapis.com/directions/v2:computeRoutes'

بعد ذلك، تحتسب الخدمة المسار المطلوب، وتُرجع الحقول التي طلبتها.

ComputeRouteMatrix

تقبل واجهة برمجة التطبيقات Routes API ComputeRouteMatrix طلب HTTP POST مع نص طلب JSON يحتوي على تفاصيل الطلب. يجب توفير نقطة منشأ واحدة على الأقل، ووجهتين أو أكثر، ووضع التنقّل، وقناع حقل لتحديد الحقول التي سيتم عرضها.

مثال

curl -X POST -d '{
  "origins": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420761,
            "longitude": -122.081356
          }
        }
      }
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.403184,
            "longitude": -122.097371
          }
        }
      }
    }
  ],
  "destinations": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420999,
            "longitude": -122.086894
          }
        }
      }
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.383047,
            "longitude": -122.044651
          }
        }
      }
    }
  ],
  "travelMode": "DRIVE"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status,condition' \
'https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix'

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

الموارد

يلخِّص الجدول التالي الموارد المتاحة من خلال واجهة برمجة التطبيقات Routes API بالإضافة إلى البيانات التي تعرِضها.

مصادر البيانات البيانات التي تم عرضها تنسيق الإرجاع
ComputeRoutes عرض المسارات والمراحل والخطوات الخاصة بمسار معيّن، مع مسارات بديلة، إذا طُلب ذلك JSON
ComputeRouteMatrix لعرض صفيف من المسارات من نقطة بدء واحدة إلى نقطة وجهة واحدة.

كيفية استخدام Routes API

1 الإعداد ابدأ بـ إعداد مشروعك على Google Cloud وأكمِل تعليمات الإعداد التالية.
2 حساب مسار ومراجعة الردّ لمزيد من المعلومات، يُرجى الاطّلاع على مقالتَي الحصول على مسار ومراجعة الردود الواردة من المسار.
3 حساب مصفوفة المسارات ومراجعة الاستجابة لمزيد من المعلومات، يُرجى الاطّلاع على مقالتَي الحصول على مصفوفة مسارات ومراجعة استجابة مصفوفة المسارات.

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

للحصول على قائمة بمكتبات العملاء المتاحة لواجهة برمجة التطبيقات Routes API، اطّلِع على مكتبات العملاء.

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