برای تولید هم‌زمان، مبدأ، حالت سفر (مانند رانندگی، دوچرخه، دوچرخه‌سواری، یا پیاده‌روی)، و محدودیت زمانی را به API ارائه دهید. همچنین می‌توانید اولویت‌های مسیریابی و ظاهر بصری چندضلعی حاصل را تنظیم کنید.
حالت‌های سفر
از پارامتر الزامی travelMode (travel_mode) برای مشخص کردن حالت
حمل‌ونقل استفاده کنید:
DRIVE: دسترسی‌پذیری را برای خودرو سواری درطول جاده‌های قابل‌رانندگی بااستفاده از محدودیت‌های سرعت اعلام‌شده، سلسله‌مراتب جاده، جریمه‌های دور زدن، و (اختیاری) شرایط ترافیک زنده محاسبه می‌کند.TWO_WHEELER: دسترسی‌پذیری را برای وسایل نقلیه موتوری دوچرخ (مانند موتورسیکلت یا اسکوتر) بااستفاده از قوانین دسترسی به جاده مختص حالت و سرعت‌های مدل‌سازی‌شده پایین‌تر ازDRIVEدر جاده‌های پرسرعت محاسبه می‌کند. درنتیجه، یک هم‌زمانTWO_WHEELERمعمولاً منطقه‌ای بزرگ‌تر ازBICYCLEاما کوچک‌تر ازDRIVEرا در امتداد بزرگراه‌های پرسرعت پوشش می‌دهد.BICYCLE: قابلیت دسترسی را برای دوچرخه‌سوار در خیابان‌های قابل‌دسترسی با دوچرخه، خطوط دوچرخه، و مسیرهای مشترک محاسبه می‌کند، با سرعت‌هایی که برای نوع جاده و شیب تنظیم شده‌اند، به‌استثنای بزرگراه‌ها و آزادراه‌های با دسترسی کنترل‌شده.WALK: دسترسی‌پذیری را برای عابر پیاده در پیاده‌روها، مسیرهای پیاده‌روی، مسیرهای کوهستانی، و خیابان‌های قابل‌دسترسی برای عابر پیاده محاسبه می‌کند و سرعت پیاده‌روی را براساس شیب تنظیم می‌کند. مسیر پیاده‌روی محدودیت‌های یک‌طرفه خودرو را نادیده می‌گیرد.
افق زمانی
محدودیت اصلی‌ای که برای سرویس ارائه می‌دهید travelDuration
(travel_duration) است. این محدودیت افق زمانی را برای محاسبه تعریف می‌کند.
- حداقل و حداکثر مدت: مدت باید حداقل
"1s"(۱ ثانیه) باشد. مدت‌های صفر ("0s")، منفی، و زیرثانیه کمتر از ۱ ثانیه (مثل"0.5s") خطای400 INVALID_ARGUMENTرا برمی‌گردانند. این میانای برنامه‌سازی کاربردی حداکثر مدت سفر ۳۶۰۰ ثانیه (۱ ساعت) را برای حالت‌هایDRIVEوTWO_WHEELER، و ۷۲۰۰ ثانیه (۲ ساعت) را برای حالت‌هایWALKوBICYCLEپشتیبانی می‌کند. - حداقل کف چندضلعی: چون میانای برنامه‌سازی کاربردی بخش‌های جاده‌ای را که به آن‌ها رسیده است به سلول‌های شبکه فضایی تبدیل می‌کند، مدت‌های بسیار کوتاه چندضلعی کوچکی را برمی‌گرداند که سلول‌های شبکه اطراف مبدأ چسبیده را پوشش می‌دهد.
- عملکرد: زمان محاسبه با مدت درخواست‌شده و حالت سفر انتخاب‌شده تغییر می‌کند. یک هم‌زمان رانندگی یک ساعته منطقه جغرافیایی و شبکه جاده‌ای بسیار بزرگ‌تری را نسبت به یک هم‌زمان پیاده‌روی یک ساعته پوشش می‌دهد، که منجر به تأخیر بیشتر برای درخواست رانندگی می‌شود.
- قالب‌بندی: چون API از
google.protobuf.Durationاستفاده می‌کند، مدت باید به‌صورت رشته‌ای که به"s"ختم می‌شود قالب‌بندی شود (برای مثال،"3600s")، نه به‌صورت عدد صحیح.
نقاط مبدأ و چسباندن به جاده
می‌توانید نقطه شروع هم‌زمان را به دو روش مشخص کنید:
- مختصات (
location): یک جفت طول و عرض جغرافیایی. هر دوlatitude(در[-90, 90]) وlongitude(در[-180, 180]) را ارائه دهید. اگر یکی از آن‌ها را حذف کنید، API آن را به‌عنوان0.0درنظر می‌گیرد که نقطه را روی خط استوا یا نصف‌النهار مبدأ قرار می‌دهد. اگر هر دو ({}) را حذف کنید یا(0, 0)را ارسال کنید، میانای برنامه‌سازی کاربردی خطای400 INVALID_ARGUMENTرا برمی‌گرداند. - شناسه‌های مکان (
place): شناسه یکتا برای مکانی خاص در Google Maps. وقتی شناسه مکان را ارائه می‌دهید، سرویس مکان را به مختصات مرکزوار آن تبدیل می‌کند و آن نقطه را به نزدیک‌ترین جاده می‌چسباند. از قالب نام منبع که باplaces/شروع می‌شود (برای مثال،places/ChIJIQBpAG2ahYAR_6128GcTUEo) استفاده کنید؛ شناسه مکان بدون پیشوندplaces/نیز پذیرفته می‌شود. برای اطلاعات بیشتر درباره شناسه‌های مکان، به شناسه‌های مکان مراجعه کنید.
صرف‌نظر از روش ورودی، اگر نقطه فیزیکی دقیق روی جاده نباشد (مثلاً داخل پارک یا ساختمان باشد)، میانای برنامه‌سازی کاربردی مدت سفر را از آن نقطه محاسبه نمی‌کند. برای مدیریت این وضعیت، این سرویس از چسباندن به جاده استفاده می‌کند. چسباندن به جاده ویژگی‌های زیر را دارد:
- چسباندن هوشمند: سرویس تلاش می‌کند نقطه مبدأ شما را به نزدیک‌ترین بخش جاده قابل‌عبور بچسباند.
- آگاهی از حالت: منطق چسباندن
travel_modeشما را درنظر می‌گیرد. اگرDRIVEیاTWO_WHEELERرا درخواست کنید، API مسیرهای مخصوص عابر پیاده را نادیده می‌گیرد و نزدیک‌ترین خیابان قابل‌رانندگی را جستجو می‌کند. اگرWALKرا درخواست کنید، API مسیرهای پیاده‌روی و پیاده‌روها را در اولویت قرار می‌دهد. - موارد ناموفق: اگر API نتواند بخش جاده مناسبی را در حداکثر فاصله چسباندن نقطه مبدأ شما (حدود ۲۰۰ متر، یا کمتر برای
WALKوBICYCLE) پیدا کند، API خطای404 NOT_FOUNDرا برمی‌گرداند. عناصر جغرافیایی بزرگ (مانند پارک‌ها، پردیس‌ها، یا نقاط دیدنی) ممکن است شناسه جا با مرکز ثقلی داشته باشند که از فاصله چسبیدن به نزدیک‌ترین جاده قابل‌استفاده برای حالت سفر دورتر باشد؛ در این موارد، به‌جای آن، مختصات صریحlocationورودی جاده را ارسال کنید.
جهت سفر (ورودی درمقابل خروجی)
می‌توانید هم دسترسی‌پذیری ورودی و هم دسترسی‌پذیری خروجی را بااستفاده از
پارامتر travelDirection (travel_direction) محاسبه کنید:
FROM(برون‌مرزی): منطقه قابل‌دسترس از نقطه مبدأ را در محدوده زمانی مشخص‌شده محاسبه می‌کند. این برای موارد استفاده‌ای مثل محدوده‌های تحویل یا پوشش خدمات مناسب است.TO(ورودی): منطقه‌ای را محاسبه می‌کند که می‌توانید از آنجا در محدوده زمانی مشخص‌شده به نقطه مبدأ سفر کنید. این برای تعیین مناطق تحت پوشش مناسب است، مثلاً اینکه کارمندان از کجا می‌توانند به دفتر مرکزی رفت‌وآمد کنند.
آگاهی از ترافیک
با پارامتر routingPreference (routing_preference) کنترل کنید که داده‌های ترافیک چگونه بر چندضلعی تولیدشده تأثیر می‌گذارد:
TRAFFIC_UNAWARE(پیش‌فرض): از محدودیت‌های سرعت جریان آزاد و سلسله‌مراتب جاده برای تولید چندضلعی هم‌زمان استفاده می‌کند. این کار باعث تولید شکلی قطعی می‌شود که براساس زمان روز نوسان نمی‌کند. این پارامتر برای تجزیه‌وتحلیل کلی یا برنامه‌ریزی سناریو پایه ایده‌آل است.TRAFFIC_AWARE: هم‌زمان‌ها را بااستفاده از شرایط ترافیک زنده در زمان دقیق پردازش درخواست محاسبه می‌کند (مُهرهای زمان عزیمت یا ورود سفارشی آینده یا گذشته در نسخه ۱ قابل‌پیکربندی نیستند). این امر باعث می‌شود که منطقه قابل‌دسترسی درطول ازدحام کوچک‌تر شود و در ساعات کم‌مصرف گسترش یابد؛ در شرایط جریان آزاد یا کم‌مصرف،TRAFFIC_AWAREوTRAFFIC_UNAWAREممکن است چندضلعی‌های تقریباً یکسانی را برگردانند. توجه: مسیریابی با اطلاع از ترافیک فقط زمانی پشتیبانی می‌شود کهtravelModeرویDRIVEیاTWO_WHEELERتنظیم شده باشد.
صاف کردن و وفاداری
بااستفاده از پارامترهای polygonFidelity (polygon_fidelity) و enableSmoothing (enable_smoothing) می‌توانید ظاهر و دقت چندضلعی‌های خروجی را سفارشی‌سازی کنید. اگرچه این گزینه‌ها مستقل هستند، اما باهم کار می‌کنند تا شکل نهایی را تعیین کنند.
polygonFidelity: وضوح سلول شبکه فضایی را که برای تخمین مرز قابل‌دسترسی استفاده می‌شود کنترل می‌کند:LOW: از بزرگ‌ترین سلول‌های جدولی (با پهنای چندصد متر) استفاده می‌کند. بهترین گزینه برای پوشش دادن مناطق بزرگ با رأس‌های کمتر و بدون شکاف‌های داخلی است که منجر به شکل کلی می‌شود که می‌تواند منطقه قابل‌دسترسی را درطول راهروهای باریک جاده بیش‌ازحد تخمین بزند.MEDIUM: دقت و تعداد رأس متعادل.HIGH: از کوچک‌ترین سلول‌های شبکه‌ای (تقریباً ۱۰۰ تا ۱۵۰ متر عرض) استفاده می‌کند. منجر به انطباق دقیق‌تر با شبکه جاده‌ای به‌دست‌آمده می‌شود، اما می‌تواند حفره‌های داخلی در جاهایی که شبکه جاده‌ای پراکنده است ایجاد کند.POLYGON_FIDELITY_UNSPECIFIED: اگر مشخص نشده باشد، سرویس به‌طور خودکار و براساس حالت و مدت سفر، وضوح را انتخاب می‌کند. برای مدت‌های کوتاه و برایWALKاز سلول‌های ریزتر و برای مدت‌های طولانی از سلول‌های درشت‌تر استفاده می‌کند. برای مقایسه هم‌زمان‌ها در مدت‌ها یا حالت‌های سفر مختلف،polygonFidelityرا به‌طور صریح تنظیم کنید.
دقت چندضلعی بالا، متوسط، و پایین
enableSmoothing: کنترل می‌کند که آیا لبه‌های پله‌ای سلول‌های شبکه تعریف‌شده توسط وفاداری گرد شوند یا نه.false(خام): پیش‌فرض. مرز تراز با شبکه را برمی‌گرداند. لبه‌ها به‌صورت پله‌ای در امتداد سلول‌های جدولی ظاهر می‌شوند. بهترین گزینه برای دقت تحلیلی، مانند آزمایش‌های دقیق نقطه در چندضلعی.true(هموارشده): گوشه‌های تیز را برای نمایش بصری نقشه گرد می‌کند درحالی‌که تقریباً مساحت هر حلقه را حفظ می‌کند. مرز دیگر از سلول‌های شبکه پیروی نمی‌کند.
هم‌زمان با هموارسازی و بدون آن