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

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

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

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

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

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

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

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

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

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

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

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

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

كيف يمكنك الاستفادة من Routes API؟

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

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

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

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

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

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

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

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

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

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

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

    • إحداثيات خط العرض وخط الطول، اختيارية مع عنوان المركبة

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

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

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

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

  • المسافة لوضع سفر محدّد

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

  • مدة الرحلة المقدَّرة في حركة المرور

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

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

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

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