ایجاد مسیرهای وسایل نقلیه بزرگ و amp; ETA ها

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

آنچه این راهنما پوشش می‌دهد: این راهنما نحوه استفاده از API مسیرها با مسیریابی وسایل نقلیه بزرگ را برای درخواست مسیرها، مسافت سفر، زمان سفر پیش‌بینی‌شده و ETAهایی که ویژگی‌های خاص یک وسیله نقلیه بزرگ مانند کامیون تجاری یا اتوبوس مسافربری را در نظر می‌گیرند، پوشش می‌دهد.

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

آنچه یاد خواهید گرفت

شما یاد خواهید گرفت که چگونه موارد زیر را انجام دهید:

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

پیش‌نیازها

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

محدودیت‌ها

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

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

درخواست مسیر کامیون بسازید

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

نقاط پایانی

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

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

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

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

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

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

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

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

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

تبدیل از امپریال به متریک

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

برای مثال:

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

A diagram illustrating the dimensions of a truck against the dimensions of an underpass

در ادامه قطعه کدی آمده است که یک نمونه از شیء vehicleInfo را نشان می‌دهد:

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

فیلدهای شیء vehicleInfo

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

میدان توضیحات یادداشت‌ها / ارزش‌ها
totalHeightMm حداکثر ارتفاع وسیله نقلیه. بر حسب میلی‌متر، گرد شده به پایین. برای جزئیات بیشتر در مورد گرد کردن، به بخش تبدیل از واحد امپریال به واحد متریک مراجعه کنید.
totalWidthMm حداکثر عرض وسیله نقلیه. بر حسب میلی‌متر، به سمت پایین گرد شده است.
totalLengthMm طول کل وسیله نقلیه و هر تریلری که با آن حمل می‌شود. بر حسب میلی‌متر، به سمت پایین گرد شده است.
totalWeightKg وزن ناخالص خودرو (شامل تریلر و بار). بر حسب کیلوگرم، به سمت پایین گرد شده است.
totalAxleCount تعداد کل محورهای وسیله نقلیه و هرگونه تریلر. دقیقاً.
trailerInfo (اختیاری) آرایه‌ای از اشیاء، یکی برای هر تریلر. برای وسیله نقلیه بدون تریلر، مانند کامیون جعبه‌ای، این مورد را حذف کنید.
hazardousGoodsTypes (اختیاری) آرایه‌ای که هرگونه مواد خطرناک موجود در کشتی را مشخص می‌کند. مواد منفجره، گازها، قابل اشتعال، قابل احتراق، آلی، سمی، خورنده، خطر استنشاق، خطر محیطی، سایر

از ماسک‌های میدانی استفاده کنید

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

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

عوارض

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

مشخص کردن avoidTolls مسیرهای بدون عوارض را در پاسخ تضمین نمی‌کند. در برخی موارد، استفاده از جاده عوارضی برای سفر بین مبدا و مقصد ضروری است. اگر routes.warnings در fieldmask درخواست 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 (به ثانیه). مدت زمان سفر در مسیریابی وسایل نقلیه بزرگ از یک مدل جدید آموزش دیده بر اساس سرعت سفر مشاهده شده کامیون‌های واقعی در شبکه جاده‌ای استفاده می‌کند. همچنین می‌توان از آن برای محاسبه ETA با اضافه کردن مدت زمان تخمینی سفر به زمان حرکت مورد انتظار استفاده کرد.
  • مسافت کل مسیر : routes.distanceMeters (به متر).
  • توکن مسیر : routes.routeToken . این یک توکن مبهم است که مسیر دقیق محاسبه شده را نشان می‌دهد. شما این توکن را به SDK ناوبری (Navigation SDK) ارسال می‌کنید تا مطمئن شوید که همان مسیر مخصوص کامیون به راننده نشان داده می‌شود. برای جزئیات بیشتر در مورد نحوه انجام این کار، راهنمای ارائه ناوبری گام به گام را بررسی کنید.
پرچم‌های ایمنی مسیر را بررسی کنید

وقتی پاسخی دریافت می‌کنید، اولین کاری که باید انجام دهید بررسی پرچم‌های ایمنی مسیر است. اگر مسیر ارائه شده شامل یک یا چند محدودیت باشد که آن را برای وسیله نقلیه نامناسب می‌کند، فیلد 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"
  },
  { ... }
]

مراحل بعدی