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

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

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

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

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

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

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

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

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

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

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

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

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

ما أهمية واجهة برمجة تطبيقات Routes API؟

باستخدام واجهة برمجة تطبيقات المسارات، يمكنك الحصول على فئتين أساسيتين من معلومات التوجيه:

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

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

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

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

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

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

    • سلسلة من نقاط الطريق، التي يمكنك تحسينها للحصول على ترتيب أكثر كفاءة للسفر إليها.

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

    • السلاسل النصية: على سبيل المثال: "شيكاغو، إلينوي"، "داروين، NT، أستراليا"، "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 يحتوي على تفاصيل الطلب. المطلوبة هي الأصل والوجهة و 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

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

مثال

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

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