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

مثال

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

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