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

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

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

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

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

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

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

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

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

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

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

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

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

ما أهمية واجهة برمجة تطبيقات 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 يحتوي على تفاصيل الطلب. يجب توفير نقطة الانطلاق ونقطة الوصول ووضع التنقّل وقناع حقل لتحديد الحقول التي سيتم عرضها.

مثال

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 يحتوي على تفاصيل الطلب. يجب توفير نقطة منشأ واحدة على الأقل ووجهتين أو أكثر ووضع التنقّل وقناع حقل لتحديد الحقول التي سيتم عرضها.

مثال

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

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