إنشاء مسارات وتقديرات لوقت الوصول للمركبات الكبيرة

الفئة المستهدَفة من هذا الدليل: هذا الدليل مخصّص للمطوّرين الذين ينشئون خدمات لتخطيط الرحلات وتنفيذها باستخدام الشاحنات أو المركبات الكبيرة الأخرى. تشمل حالات الاستخدام ذات الصلة حساب أوقات التنقّل والمسافات أو احتساب الأوقات المقدَّرة للوصول أو إنشاء مسارات سيستخدمها تطبيق تنقّل.

المحتوى الذي يغطّيه هذا الدليل: يوضّح هذا الدليل كيفية استخدام Routes API مع ميزة "توجيه المركبات الكبيرة" لطلب المسارات ومسافة التنقّل ووقت التنقّل المتوقّع والأوقات المقدَّرة للوصول التي تأخذ في الاعتبار السمات المحدّدة للمركبة الكبيرة، مثل شاحنة تجارية أو حافلة ركاب.

للتعرّف على كيفية إجراء عمليات حساب على مستوى أسطول المركبات الكبيرة باستخدام Route Optimization API، يُرجى الاطّلاع على مستندات توجيه الشاحنات في Route Optimization API.

أهداف الدورة التعليمية

ستتعرّف على كيفية إجراء ما يلي:

  • إنشاء طلب توجيه صالح
  • تحديد ملف تعريف مركبة لمركبتك الحقيقية، باستخدام الأبعاد والوزن والخصائص الأخرى
  • تفسير الردّ، بما في ذلك رمز المسار وعلامات الأمان أثناء التنقّل

المتطلبات الأساسية

  1. يجب إنشاء مشروعك على Google Cloud وتفعيل Routes API.
  2. يجب تجهيز مشروعك لاستخدام ميزة "توجيه المركبات الكبيرة". يُرجى التواصل مع ممثل عن Google لإكمال هذه الخطوة.

القيود

قبل البدء، يجب أن تكون على دراية بالقيود والمتطلبات التالية.

  • التوفّر الجغرافي: لا تتوفّر ميزة "توجيه المركبات الكبيرة" إلا في الولايات المتحدة المتجاورة الـ 48.
  • ميزة "توجيه المركبات الكبيرة" هي عرض في مرحلة المعاينة. يجب ألا يعتمد السائقون فقط على المسارات التي تعرضها واجهة برمجة التطبيقات هذه للتأكّد من أنّها آمنة أو قانونية. لا نضمن أن تكون المسارات مناسبة للمركبة، وقد يؤدي اتّباعها إلى تعريض السائقين لمخاطر، مثل الجسور المنخفضة أو الطرق التي يُحظر فيها استخدام المركبات الكبيرة.
  • المسارات التي يتم بذل قصارى الجهد لإنشائها : في بعض الحالات، لا يمكن لواجهة برمجة التطبيقات العثور على مسار يتوافق تمامًا مع قيود التنقّل. بدلاً من ذلك، تعرض واجهة برمجة التطبيقات مسارًا "يتم بذل قصارى الجهد لإنشائه" قد يمرّ بمناطق محظورة. تضع Routes API علامة واضحة على هذه المسارات في الحقل routeRestrictionsPartiallyIgnored. في هذه الحالات، يجب التخطيط للمسار بعناية، ويُفضّل استخدام بيانات مصدر أخرى. لا تستخدِم مسارًا تم وضع علامة عليه كمصدر وحيد للحقيقة من أجل التخطيط أو التنقّل.
  • الميزات غير المتوافقة: نعمل على إضافة المزيد من الوظائف إلى هذا العرض، ولكن لا تتيح ميزة "توجيه المركبات الكبيرة" ما يلي:
    • أسعار رسوم العبور للشاحنات
    • حدود السرعة
    • توجيه المواد الخطرة المشعّة
  • حدود الاستخدام: تخضع جميع الطلبات لحدود طلبات البحث العادية في الثانية (QPS) limits.

إنشاء طلب مسار شاحنة

للحصول على مسار شاحنة، عليك إرسال طلب HTTPS إلى نقطة نهاية Routes API باستخدام مَعلمات محدّدة تصف مركبتك.

نقاط النهاية

يمكنك استخدام نقطتَي نهاية لتوجيه الشاحنات:

  • computeRoutes: تحسب مسارًا واحدًا بين نقطة انطلاق واحدة ونقطة نهاية واحدة.
  • computeRouteMatrix: تحسب المسافة والمدة لمصفوفة من نقاط البداية والوجهات، ولكن لا تعرض خطًا متعدد الخطوط للمسار.

مَعلمات الطلب الرئيسية

في نص الطلب، يجب تضمين ما يلي:

  • travelMode: اضبط هذه القيمة على TRUCK.
  • routingPreference: اضبط هذه القيمة على TRAFFIC_AWARE_OPTIMAL.
  • routeModifiers: تحتوي هذه الحاوية على الكائن vehicleInfo الذي تحدّد فيه سمات مركبتك. يتم وصف الكائن vehicleInfo بالتفصيل أدناه.

تحديد ملف تعريف مركبة

لإرسال طلب، يجب تقديم نص طلب يتضمّن كائن vehicleInfo يصف مركبتك. يمكنك اعتبار هذه المعلومات بمثابة مواصفات تتطابق مع التفاصيل المادية لمركبتك الحقيقية. تتطلّب الخدمة هذه التفاصيل لعرض المسارات التي تأخذ في الاعتبار القيود المفروضة على الطرق استنادًا إلى سمات مركبتك.

قياسات المركبة

يُرجى تقديم وزن المركبة بالكيلوغرام وأبعادها بالميلليمتر، كما هو موضّح في أسماء الحقول. على سبيل المثال، يجب تقديم الارتفاع الإجمالي بالميلليمتر (totalHeightMm). بما أنّ أبعاد الشاحنات غالبًا ما يتم التعبير عنها بالأقدام أو الأمتار، قد يتطلّب ذلك تحويل الوحدات.

التحويل من الوحدات الإمبراطورية إلى الوحدات المترية

عند التحويل من الوحدات الإمبراطورية، يجب دائمًا مراعاة أبعاد مركبتك المحدّدة إلى جانب الحدود القصوى القياسية لأحجام الطرق والأنفاق. قد يكون هذا الأمر مهمًا بشكل خاص مع القيم الكسرية. استنادًا إلى حجم المركبة الفعلية، يمكن أن يؤدي تقريب القيمة الكسرية إلى الأعلى إلى توجيه المركبة بشكل مفرط.

على سبيل المثال:

  • العرض: يبلغ عرض العديد من المقطورات في الولايات المتحدة 8 أقدام و6 بوصات، ما يعادل 2,590.8 ملم. إذا تم تقريب القيمة إلى 2,591 ملم، سيشير ذلك إلى أنّ عرض المركبة أكبر من 8 أقدام و6 بوصات، ما سيصنّفها كمركبة كبيرة الحجم على الطرق الأمريكية. سيؤدي ذلك بعد ذلك إلى إنشاء مسار تم حسابه وفقًا لقيود مختلفة بشكل كبير عن القيود المقصودة.
  • الارتفاع: لن يكون المسار الذي يؤدي إلى جسر يبلغ ارتفاعه 11 قدمًا مناسبًا لـ شاحنة جرّارة عادية يبلغ ارتفاعها 13.5 قدمًا. ومع ذلك، ستتمكّن الشاحنات الصغيرة التي يبلغ ارتفاعها حوالي 10 أقدام من التنقّل في النفق. وبناءً على ذلك، من الضروري تحديد سمات مركبتك بدقة.

مخطط يوضّح أبعاد شاحنة مقارنةً بأبعاد ممر سفلي

في ما يلي مقتطف الرمز البرمجي يعرض مثالاً على كائن vehicleInfo:

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

حقول الكائن vehicleInfo

يعرض الجدول التالي جميع تعريفات المركبات والحمولة التي يمكنك إرسالها مع الطلب.

الحقل الوصف ملاحظات / القيم
totalHeightMm الحد الأقصى لارتفاع المركبة بالميلليمتر، يتم تقريب القيمة إلى الأدنى لمزيد من التفاصيل حول التقريب، يُرجى الاطّلاع على التحويل من الوحدات الإمبراطورية إلى الوحدات المترية.
totalWidthMm الحد الأقصى لعرض المركبة بالميلليمتر، يتم تقريب القيمة إلى الأدنى
totalLengthMm الطول الإجمالي المجمّع للمركبة وأي مقطورات بالميلليمتر، يتم تقريب القيمة إلى الأدنى
totalWeightKg الوزن الإجمالي للمركبة (بما في ذلك المقطورات والحمولة) بالكيلوغرام، يتم تقريب القيمة إلى الأدنى
totalAxleCount العدد الإجمالي للمحاور في المركبة وأي مقطورات القيمة الدقيقة
trailerInfo (اختياري) مصفوفة من الكائنات، واحد لكل مقطورة يجب حذف هذا الحقل لمركبة بدون مقطورات، مثل شاحنة نقل
hazardousGoodsTypes (اختياري) مصفوفة تحدّد أي مواد خطرة على متن المركبة EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER

استخدام أقنعة الحقول

للحصول على أفضل النتائج، يُرجى تضمين العنوان X-Goog-FieldMask في طلبك لتحديد الحقول التي تريدها بالضبط في الردّ. تؤدي أقنعة الحقول إلى تقليل وقت الاستجابة وتضمن تلقّي الحقول الاستشارية المهمة. كحد أدنى، يجب دائمًا تضمين routes.travelAdvisory.routeRestrictionsPartiallyIgnored في قناع الحقل، لأنّ هذا يشير إلى ما إذا كان المسار يتضمّن قيدًا واحدًا أو أكثر ينطبق على مركبتك.

لمزيد من التفاصيل حول أقنعة الحقول مع Routes API، يُرجى الاطّلاع على هذه المقالة.

رسوم العبور

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

لا يضمن تحديد avoidTolls عرض مسارات مجانية في الردّ. في بعض الحالات، يكون استخدام طريق برسوم عبور مطلوبًا للتنقّل بين نقطة البداية والنهاية. إذا تضمّنت routes.warnings في قناع الحقل الخاص بطلب بيانات من واجهة برمجة التطبيقات Routes API، سيتم وضع علامة على المسارات التي تحتوي على طرق برسوم عبور وفقًا لذلك ضمن هذا الحقل.

مثال على طلب curl كامل

في ما يلي طلب curl كامل لشاحنة عادية ذات مقطورة نصفية. يتضمّن هذا المثال نقطة النهاية والعناوين ونص الطلب.

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

تفسير الردّ من `computeRoutes`

يعرض الطلب الناجح إلى Routes API كائن استجابة بتنسيق JSON يحتوي على مسار واحد أو أكثر من المسارات المحتمَلة.

حقول الردّ الرئيسية

  • الشكل الهندسي للمسار المُرمَّز: routes.polyline يمكن استخدام هذا الحقل لعرض المسار على الخريطة.
  • المدة المقدَّرة للرحلة: routes.duration (بالثواني). تستخدم مدة الرحلة في ميزة "توجيه المركبات الكبيرة" نموذجًا جديدًا تم تدريبه على سرعات التنقّل المرصودة للشاحنات الفعلية على سطح شبكة الطرق. يمكن أيضًا استخدامها لحساب الوقت المقدَّر للوصول عن طريق إضافة المدة المقدَّرة للرحلة إلى وقت المغادرة المتوقّع.
  • المسافة الإجمالية للمسار: routes.distanceMeters (بالأمتار).
  • رمز المسار: routes.routeToken. هذا الرمز المميّز غير الشفاف يمثّل المسار المحسوب بدقة. يمكنك تمرير هذا الرمز المميّز إلى Navigation SDK لضمان عرض المسار نفسه الخاص بالشاحنة للسائق. لمزيد من التفاصيل حول كيفية إجراء ذلك، يُرجى مراجعة دليل توفير التنقّل المفصّل.

التحقّق من علامات الأمان للمسار

عند الحصول على ردّ، أول ما يجب فعله هو التحقّق من علامات الأمان للمسار. إذا كان المسار المقدَّم يتضمّن قيدًا واحدًا أو أكثر يجعله غير مناسب للمركبة، سيتم ضبط الحقل travelAdvisory.routeRestrictionsPartiallyIgnored على true.

يعمل هذا الحقل كعلامة للإجابة عن السؤال "هل تم وضع علامة على هذا المسار بسبب مشكلة محتمَلة؟"

  • false(أو تم حذفه من الردّ): لم يتم وضع علامة على المسار. عثر النظام على مسار يُعتقد أنّه متوافق تمامًا مع المَعلمات التي قدّمتها في الطلب.
  • true: تم وضع علامة على المسار. لم يتمكّن النظام من العثور على مسار متوافق تمامًا وعرض مسارًا "يتم بذل قصارى الجهد لإنشائه" قد لا يكون آمنًا أو قانونيًا. يجب استخدام هذا المسار بحذر شديد.

مثال: الردّ من computeRoutes

هذا مثال على ردّ للطلب الموضّح أعلاه. يُرجى العِلم أنّه في الكائن travelAdvisory، لم يتم تضمين العلامة routeRestrictionsPartiallyIgnored. يشير ذلك إلى أنّ المسار لم يتم وضع علامة عليه ويُعتقد أنّه متوافق تمامًا مع ملف تعريف المركبة.

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

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

لحساب أوقات التنقّل للعديد من الرحلات المحتمَلة في آنٍ واحد، استخدِم نقطة النهاية computeRouteMatrix للتخطيط على مستوى عالٍ من أجل مقارنة أوقات التنقّل والمسافات بكفاءة بين العديد من نقاط البداية والنهاية. على سبيل المثال، يمكنك استخدامها للعثور على أقرب شاحنة إلى موقع جديد لاستلام الشحنة. بعد تحديد نقطة بداية المركبة التي تريد استخدامها لغرضك، يمكنك إرسال طلب computeRoutes للحصول على تفاصيل المسار ورمز المسار للمركبة المقترَحة.

لاستخدام computeRouteMatrix، عليك تحديد vehicleInfo ضمن كل كائن مصدر.

مثال على الطلب

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

مثال على إجابة

الردّ هو مصفوفة يحتوي كل كائن فيها على المدة وdistanceMeters لزوج واحد من نقطة البداية والنهاية.

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

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