تولید مسیرها و زمان‌های تقریبی ورود برای وسایل نقلیه بزرگ

این راهنما برای چه کسانی است: اگر توسعه‌دهنده‌ای هستید که سرویس‌هایی برای برنامه‌ریزی و اجرای سفر بااستفاده از کامیون یا سایر وسایل نقلیه بزرگ می‌سازید، این راهنما را بخوانید. موارد استفاده مرتبط شامل محاسبه زمان و مسافت سفر، محاسبه زمان تخمینی ورود، یا تولید مسیرهایی است که توسط برنامه پیمایش استفاده می‌شود.

موضوعات این راهنما: این راهنما نحوه استفاده از Routes API با «مسیریابی خودروهای بزرگ» را برای درخواست مسیر، مسافت سفر، مدت سفر پیش‌بینی‌شده، و زمان تخمینی ورود که ویژگی‌های خاص خودروهای بزرگ (مانند کامیون تجاری یا اتوبوس مسافربری) را درنظر می‌گیرد پوشش می‌دهد.

برای کسب اطلاعات درباره نحوه انجام محاسبات در سطح ناوگان برای خودروهای بزرگ بااستفاده از Route Optimization API، به سند مسیریابی کامیون Route Optimization مراجعه کنید.

آنچه خواهید آموخت

با نحوه انجام کارهای زیر آشنا خواهید شد:

• درخواست مسیریابی معتبری بسازید.
• اطلاعات خودرو واقعی‌تان را بااستفاده از ابعاد، وزن، و دیگر مشخصات تعیین کنید.
• پاسخ را تفسیر کنید، ازجمله توکن مسیر و پرچم‌های ایمنی سفر.

پیش‌نیازها

1. پروژه Google Cloud شما باید ایجاد شده باشد و Routes API باید فعال باشد.
2. پروژه شما باید برای «مسیریابی خودروهای بزرگ» آماده شده باشد. مسیریابی خودروهای بزرگ برای مجموعه محدودی از مشتریان دردسترس است، برای درخواست دسترسی با ما تماس بگیرید

محدودیت‌ها

قبل‌از شروع، باید از محدودیت‌ها و الزامات زیر آگاه باشید.

• دردسترس بودن جغرافیایی: مسیریابی خودروهای بزرگ در ۴۸ ایالت به‌هم‌پیوسته ایالات متحده (به‌طور کلی دردسترس است) و ژاپن (آزمایشی) دردسترس است. این ویژگی در آلاسکا، هاوایی، یا قلمروهای ایالات متحده دردسترس نیست.
• توصیه‌های ایمنی و رانندگی. رانندگان نباید صرفاً به مسیرهای بازگردانده‌شده توسط این API برای ایمن یا قانونی بودن اتکا کنند. تضمین نمی‌شود که مسیرها برای خودرو مناسب باشند و دنبال کردن آن‌ها ممکن است رانندگان را درمعرض خطراتی مثل پل‌های کم‌ارتفاع یا جاده‌هایی که ورود خودروهای بزرگ به آن‌ها ممنوع است قرار دهد.
• مسیرهای با بهترین تلاش. در برخی موارد، API نمی‌تواند مسیری پیدا کند که کاملاً با محدودیت‌های سفر مطابقت داشته باشد. درعوض، مسیری را که «بهترین تلاش» است برمی‌گرداند که ممکن است همچنان از مناطق محدودشده عبور کند. پاسخ Routes API این مسیرها را به‌وضوح در فیلد routeRestrictionsPartiallyIgnored پرچم‌گذاری می‌کند. در این موارد، مسیرتان را با دقت برنامه‌ریزی کنید و درصورت امکان از داده‌های منبع دیگری استفاده کنید. از مسیر پرچم‌گذاری‌شده به‌عنوان تنها منبع حقیقت برای برنامه‌ریزی یا ناوبری استفاده نکنید.
• ویژگی‌های پشتیبانی‌نشده: مسیریابی خودروهای بزرگ از موارد زیر پشتیبانی نمی‌کند:
  • قیمت عوارض کامیون
  • حد سرعت
  • مسیرهای مواد خطرناک رادیواکتیو
• محدودیت‌های استفاده: همه درخواست‌ها مشمول محدودیت‌های استاندارد پُرسمان در ثانیه (QPS) هستند.

ایجاد درخواست مسیر کامیون

برای دریافت مسیر کامیون، یک درخواست HTTPS به نقطه پایانی Routes API با پارامترهای خاصی که خودرو شما را توصیف می‌کنند ارسال می‌کنید. مفاهیم این بخش هم برای درخواست‌های تک‌مسیر و هم برای درخواست‌های ماتریس مسیر اعمال می‌شود.

نقطه پایانی

می‌توانید از دو نقطه پایانی برای مسیریابی کامیون استفاده کنید:

• computeRoutes: یک مسیر را بین یک مبدأ و یک مقصد محاسبه می‌کند.
• computeRouteMatrix: مسافت و مدت‌زمان را برای ماتریسی از مبدأها و مقصدها محاسبه می‌کند، اما چندخطی مسیر را برنمی‌گرداند.

پارامترهای درخواست کلید

در بدنه درخواست، باید پارامترهای زیر را برای فعال کردن مسیریابی کامیون اضافه کنید:

• travelMode: این مقدار را روی TRUCK تنظیم کنید.
• routingPreference: این مقدار را روی TRAFFIC_AWARE_OPTIMAL تنظیم کنید.
• routeModifiers: این شیء حاوی شیء vehicleInfo است که در آن مشخصه‌های خودروتان را تعریف می‌کنید. شیء vehicleInfo به‌طور مفصل در زیر شرح داده شده است.

مشخص کردن مشخصه‌های خودرو

برای ارسال درخواست، باید بدنه درخواست را با شیء vehicleInfo که خودرو شما را توصیف می‌کند ارائه دهید. این اطلاعات را به‌عنوان مشخصاتی درنظر بگیرید که با جزئیات فیزیکی خودرو واقعی شما مطابقت دارد. این سرویس برای برگرداندن مسیرهایی که محدودیت‌های جاده‌ای را براساس ویژگی‌های خودرو شما درنظر می‌گیرند، به این جزئیات نیاز دارد.

اندازه‌گیری‌های خودرو

وزن خودرو را به کیلوگرم و ابعاد خودرو را به میلی‌متر، همان‌طور که در نام فیلدها نشان داده شده است، ارائه دهید. برای مثال، ارتفاع کل باید برحسب میلی‌متر (totalHeightMm) ارائه شود. ازآنجایی‌که ابعاد کامیون اغلب برحسب فوت یا متر بیان می‌شود، ممکن است نیاز به تبدیل واحد باشد.

تبدیل از سلطنتی به متری

هنگام تبدیل از واحدهای امپریال، همیشه ابعاد خاص خودرو خود را در کنار محدودیت‌های اندازه استاندارد جاده و زیرگذر در نظر بگیرید. این موضوع به‌ویژه درمورد مقادیر کسری می‌تواند مهم باشد. بسته به اندازه واقعی خودرو، گرد کردن مقدار کسری می‌تواند منجر به مسیریابی بیش‌ازحد محدودکننده برای خودرو شود.

برای مثال:

• عرض: بسیاری از تریلرهای ایالات متحده عرضی معادل ۸ فوت و ۶ اینچ دارند که به ۲٬۵۹۰٫۸ میلی‌متر تبدیل می‌شود. گرد کردن به ۲۵۹۱ میلی‌متر نشان می‌دهد که وسیله نقلیه بزرگ‌تر از ۸ فوت و ۶ اینچ است که آن را به‌عنوان وسیله نقلیه بسیار بزرگ در جاده‌های ایالات متحده طبقه‌بندی می‌کند. این امر منجر به مسیری می‌شود که براساس محدودیت‌های کاملاً متفاوتی نسبت‌به آنچه مدنظر بوده محاسبه شده است.
• ارتفاع: مسیری که از زیر پلی با ارتفاع ۱۱ فوت می‌گذرد برای تریلر تراکتور معمولی با ارتفاع ۱۳٫۵ فوت مناسب نیست. اما کامیون‌های جعبه‌ای کوچک‌تر حدود ۱۰ فوتی می‌توانند از زیرگذر عبور کنند. بنابراین، مشخص کردن دقیق ویژگی‌های خودرو بسیار مهم است.

در زیر تکه‌کدی وجود دارد که نمونه‌ای از شیء vehicleInfo را نشان می‌دهد:

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

vehicleInfo فیلد شیء

جدول زیر همه تعاریف خودرو و بار را که می‌توانید با درخواست ارسال کنید نشان می‌دهد.

استفاده از پوشش فیلد

برای بهترین نتایج، سرصفحه X-Goog-FieldMask را در درخواستتان اضافه کنید تا دقیقاً فیلدهایی را که می‌خواهید در پاسخ باشد مشخص کنید. پوشش‌های فیلد تأخیر را کاهش می‌دهند و تضمین می‌کنند که فیلدهای مشاوره‌ای مهم را دریافت کنید. حداقل، همیشه routes.travelAdvisory.routeRestrictionsPartiallyIgnored را در ماسک فیلد بگنجانید، زیرا این نشان می‌دهد که آیا مسیر یک یا چند محدودیت دارد که برای خودرو شما اعمال می‌شود یا نه.

برای جزئیات بیشتر درباره FieldMasks با Routes API، این مقاله را ببینید.

راه‌های عوارضی

برای ترجیح دادن مسیرهای بدون عوارض، avoidTolls را در ویژگی routeModifiers درخواست مشخص کنید. برای اطلاعات بیشتر درباره اصلاح‌کننده‌های مسیر، مشخص کردن ویژگی‌های مسیر برای اجتناب را ببینید.

مشخص کردن avoidTolls تضمین نمی‌کند که مسیرهای بدون عوارض در پاسخ ارائه شود. در برخی موارد، برای سفر بین مبدأ و مقصد باید از جاده عوارضی استفاده کنید. اگر routes.warnings را در ماسک فیلد درخواست Routes API خود بگنجانید، مسیرهای حاوی جاده‌های عوارضی به‌طور مناسب در این فیلد حاشیه‌نویسی خواهند شد.

سایر رفتارهای مسیریابی

وقتی travelMode را روی TRUCK تنظیم می‌کنید، API به‌طور خودکار مسیر را برای مانورپذیری وسایل نقلیه بزرگ بهینه‌سازی می‌کند. مسیرهای تولیدشده از دوربرگردان‌ها اجتناب می‌کنند و جاده‌های بین‌ایالتی و بزرگراه‌ها را به‌شدت به جاده‌های کوچک‌تر ترجیح می‌دهند. برای فعال کردن این رفتارها، نیازی به تنظیم هیچ پارامتر یا اصلاح‌کننده دیگری ندارید.

محاسبه یک مسیر با computeRoutes

از نقطه پایانی computeRoutes برای محاسبه مسیر ویژه کامیون بین یک مبدأ و یک مقصد استفاده کنید.

نمونه درخواست computeRoutes

در اینجا یک درخواست 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

این یک پاسخ نمونه برای درخواست قبلی نشان‌داده‌شده در بالا است. توجه داشته باشید که در شیء travelAdvisory، پرچم routeRestrictionsPartiallyIgnored گنجانده نشده است. این نشان می‌دهد که مسیر پرچم‌گذاری نشده است و تصور می‌شود که کاملاً با ویژگی‌های خودرو مطابقت دارد.

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

تفسیر پاسخ computeRoutes

درخواست موفق به نقطه پایانی computeRoutes یک شیء پاسخ JSON حاوی یک یا چند مسیر ممکن را برمی‌گرداند.

فیلدهای پاسخ کلیدی

• هندسه مسیر کدبندی‌شده: routes.polyline. از این مورد می‌توان برای ارائه مسیر روی نقشه استفاده کرد.
• مدت تخمینی سفر: routes.duration (به ثانیه). مدت سفر مسیریابی خودروهای بزرگ از مدل جدیدی استفاده می‌کند که براساس سرعت‌های مشاهده‌شده کامیون‌های واقعی در شبکه جاده‌ای آموزش دیده است. همچنین می‌توان از آن برای محاسبه زمان تخمینی رسیدن با افزودن مدت تخمینی سفر به زمان موردانتظار حرکت استفاده کرد.
• کل مسافت مسیر: routes.distanceMeters (به متر).
• نشانه مسیر: routes.routeToken. این یک توکن مبهم است که مسیر دقیق محاسبه‌شده را نشان می‌دهد. این توکن را به Navigation SDK ارسال می‌کنید تا مطمئن شوید که همان مسیر ویژه کامیون به راننده نشان داده می‌شود. برای جزئیات، به راهنماهای کیت توسعه نرم‌افزار ناوبری برای Android یا iOS مراجعه کنید.

بررسی پرچم‌های ایمنی مسیر

وقتی پاسخی دریافت می‌کنید، اولین کاری که باید انجام دهید این است که پرچم‌های ایمنی مسیر را بررسی کنید. اگر مسیر ارائه‌شده حاوی یک یا چند محدودیت باشد که آن را برای خودرو نامناسب کند، فیلد travelAdvisory.routeRestrictionsPartiallyIgnored روی true تنظیم می‌شود.

این فیلد به‌عنوان پرچمی برای پاسخ به این سؤال عمل می‌کند: «آیا این مسیر برای مشکل احتمالی پرچم‌گذاری شده است؟»

• false(یا از پاسخ حذف شده است): مسیر پرچم‌گذاری نشده است. سیستم مسیری پیدا کرد که به‌نظر می‌رسد با پارامترهایی که در درخواست ارائه کرده‌اید کاملاً مطابقت دارد.
• true: مسیر پرچم‌گذاری شده است. سیستم نتوانست مسیری کاملاً منطبق پیدا کند و مسیری را که «بهترین تلاش» بود برگرداند که ممکن است ایمن یا قانونی نباشد. این مسیر باید با احتیاط بسیار استفاده شود.

محاسبه ماتریس مسیرها (computeRouteMatrix)

از نقطه پایانی computeRouteMatrix برای مقایسه کارآمد زمان سفر و فاصله بین مبدأها و مقصدهای متعدد استفاده کنید. برای مثال، ممکن است از آن برای پیدا کردن نزدیک‌ترین کامیون به مکان جدید سوار کردن مسافر استفاده کنید. وقتی مبدأ خودرویی را که می‌خواهید برای هدفتان استفاده کنید شناسایی کردید، می‌توانید درخواست computeRoutes صادر کنید تا جزئیات مسیر و کد مسیر را برای خودرو پیشنهادی دریافت کنید.

برای استفاده از computeRouteMatrix، باید vehicleInfo را در هر شیء origin مشخص کنید، نه در ریشه درخواست.

نمونه درخواست computeRouteMatrix

{
  "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"
}

نمونه پاسخ computeRouteMatrix

پاسخ آرایه‌ای است که هر شیء آن حاوی مدت و distanceMeters برای یک جفت مبدأ-مقصد است.

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

مراحل بعدی

• ارائه ناوبری گام‌به‌گام: با نحوه استفاده از routeToken در کیت توسعه نرم‌افزار ناوبری برای Android یا iOS آشنا شوید.
• بهینه‌سازی در سطح ناوگان را انجام دهید: از Route Optimization API با Large Vehicle Routing استفاده کنید.
• مرجع میانای برنامه‌سازی کاربردی: برای فهرست کامل همه فیلدها و مقادیر ممکن، مرجع Routes API را ببینید.