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

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

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

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

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

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

  • جانب الطريق مخصّص لخدمات الاصطحاب أو النقل

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

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

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

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

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

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

ما هي الإجراءات التي يمكنك تنفيذها باستخدام 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

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

مثال

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، اطّلِع على مكتبات العملاء.

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