نظرة عامة على 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 API: ComputeRoute وComputeRouteMatrix.

ComputeRoute

تقبل طريقة Routes API ComputeRoute طلب HTTP POST مع نص طلب JSON يحتوي على تفاصيل الطلب. القيم المطلوبة هي origin وdestination و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'

بعد ذلك، تحسب الخدمة المسار المطلوب وتعرض الحقول التي طلبتها.

مصفوفة ComputeRoute

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

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

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

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

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

للحصول على قائمة بمكتبات العملاء المتاحة لواجهة برمجة تطبيقات Routes، راجِع مكتبات العملاء.

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