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

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

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

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

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

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

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

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

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

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

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

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

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

ما الذي يمكنك فعله باستخدام Routes API؟

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

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

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

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

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

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

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

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

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

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

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

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

  • ضبط خيارات مساراتك بناءً على احتياجاتك وأهدافك:

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

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

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

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

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

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

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

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

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

طريقة عمل Routes API

ثمة طريقتان لواجهة برمجة تطبيقات Routes: ComputeRoute وComputeRouteMatrix.

ComputeRoute

تقبل طريقة Routes API ComputeRoute طلب 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 مع البيانات التي تعرضها.

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

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

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

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

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

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