ابزار compute_routes مسیری را بین مبدأ و مقصد برای حالت سفر مشخصی برمی‌گرداند. پاسخ شامل مسافت و مدت‌زمان مسیر است. به‌طور پیش‌فرض، مسیرها بدون ترافیک زنده محاسبه می‌شوند.
Pro مسیریابی را اضافه می‌کند
که ترافیک زنده و مسیرهای دارای توقف‌های میانی بیشتر را درنظر می‌گیرد.
این صفحه گزینه‌های درخواست، ازجمله گزینه‌های Pro، محتوای پاسخ، و نحوه صدور صورت‌حساب برای درخواست‌ها را شرح می‌دهد. برای طرح‌واره کامل ابزار،
مرجع compute_routes را ببینید.
گزینه‌های درخواست
| گزینه | شرح |
|---|---|
origin، destination |
الزامی. هرکدام یک نقطه‌مسیر است: یک address (نشانی قابل‌خواندن برای انسان یا یک plus code)، یک place_id، یا یک lat_lng. می‌توانید قالب‌ها را ترکیب کنید، مثلاً نشانی برای مبدأ و شناسه مکان برای مقصد. |
travel_mode |
حالت حمل‌ونقل: DRIVE (پیش‌فرض)، WALK، BICYCLE، یا TRANSIT. مسیرهای WALK در مرحله بتا هستند و ممکن است گاهی پیاده‌روهای مشخص یا مسیرهای عابر پیاده را نشان ندهند. باید این هشدار را برای همه مسیرهای پیاده‌روی که در برنامه‌تان نمایش می‌دهید به کاربر نشان دهید. |
routing_preference |
نحوه استفاده از داده‌های ترافیک برای محاسبه مسیر: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (پیش‌فرض) یا ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL، که گزینه Pro است. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL برای WALK یا BICYCLE پشتیبانی نمی‌شود. مسیریابی با درنظر گرفتن ترافیک را ببینید. |
intermediate_waypoints |
ایستگاه‌های مرتب‌شده بین مبدأ و مقصد. مسیر به‌ترتیب ارائه‌شده از آن‌ها عبور می‌کند. درخواست می‌تواند شامل حداکثر ۱۰ نقطه‌مسیر میانی، یا ۱۱ تا ۲۵ نقطه‌مسیر به‌عنوان گزینه Pro باشد. درخواست با بیش‌از ۲۵ مورد، خطای INVALID_ARGUMENT را برمی‌گرداند. مسیرهای حمل‌ونقل عمومی از نقطه‌مسیرهای میانی پشتیبانی نمی‌کنند. |
departure_time یا arrival_time |
زمان حرکت از مبدأ یا رسیدن به مقصد، به‌صورت مُهر زمان RFC 3339. حداکثر یک مورد تنظیم کنید. به‌طور پیش‌فرض زمان حرکت را زمان فعلی درنظر می‌گیرد. برای TRANSIT، زمان می‌تواند حداکثر ۷ روز در گذشته یا ۱۰۰ روز در آینده باشد. برای حالت‌های دیگر سفر، زمان نمی‌تواند در گذشته باشد و می‌تواند حداکثر ۳۶۵ روز جلوتر باشد. |
compute_alternative_routes |
وقتی true، پاسخ علاوه‌بر مسیر توصیه‌شده، شامل مسیرهای جایگزین نیز می‌شود (درصورت دردسترس بودن جایگزین‌ها). پیش‌فرض‌ها به false. |
include_polyline |
وقتی true، هر مسیر در پاسخ شامل encodedPolyline است. پیش‌فرض‌ها به false. |
location_bias |
عرض و طول جغرافیایی که نحوه حل‌وفصل نقطه‌مسیرهای نوشتاری را سوگیری می‌کند، برای مثال برای ابهام‌زدایی از نشانی. |
گزینه‌های Pro
دو گزینه Pro SKU را انتخاب می‌کنند. درخواستی که از یکی یا هر دو استفاده می‌کند، تحت شناسه Pro صورت‌حساب می‌شود:
| گزینه Pro | زمان استفاده از آن |
|---|---|
routing_preference روی ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL تنظیم شد |
کاربر درباره ترافیک، ازدحام، یا مدت سفر با درنظر گرفتن ترافیک فعلی سؤال می‌کند. مسیریابی با درنظر گرفتن ترافیک را ببینید. |
۱۱ تا ۲۵ intermediate_waypoints |
مسیر به بیش‌از ۱۰ توقف بین مبدأ و مقصد نیاز دارد. |
همه گزینه‌های دیگر تحت SKU «ضروریات» صورت‌حساب می‌شوند، ازجمله حالت سفر، زمان‌بندی، مسیرهای جایگزین، چندخطی‌ها، و سوگیری مکان.
مسیریابی با درنظر گرفتن ترافیک
به‌طور پیش‌فرض، مسیرها بدون شرایط ترافیک زنده محاسبه می‌شوند
(ROUTING_PREFERENCE_TRAFFIC_UNAWARE). این تنظیم کمترین تأخیر را دارد. این حالت برای درخواست‌هایی مناسب است که ترافیک در آن‌ها اهمیتی ندارد یا اعمال نمی‌شود، مثل مسیرهای پیاده‌روی یا برنامه‌ریزی‌های کلی.
routing_preference را روی ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL تنظیم کنید تا
مسیر و مدت آن با شرایط ترافیک فعلی محاسبه شود، وقتی
داده‌های ترافیک دردسترس باشد. وقتی کاربر می‌پرسد رانندگی درحال‌حاضر چقدر طول می‌کشد، از این عبارت استفاده کنید. برای مسیرهای TRANSIT، این تنظیم از داده‌های هم‌زمان حمل‌ونقل عمومی، مثل تأخیرها و لغوها، درصورت دردسترس بودن استفاده می‌کند. برای مسیرهای WALK یا BICYCLE پشتیبانی نمی‌شود؛ این درخواست‌ها خطای INVALID_ARGUMENT برمی‌گردانند. این گزینه
Pro است، بنابراین درخواست تحت شناسه محصول Pro صورت‌حساب می‌شود. این گزینه همچنین تأخیر را افزایش می‌دهد.
درطول «دسترسی عمومی محدودشده»، اگر پروژه‌تان در فهرست مجاز Pro نباشد، این گزینه
به‌عنوان ROUTING_PREFERENCE_TRAFFIC_UNAWARE درنظر گرفته می‌شود. برای جزئیات،
گزینه‌های Pro درطول «دسترسی عمومی محدودشده» را ببینید.
مثال
درخواست زیر یک مسیر رانندگی با آگاهی از ترافیک با یک توقف میانی و یک چندخطی کدگذاری‌شده را درخواست می‌کند. تحت شناسه Pro صورت‌حساب صادر می‌شود:
{
"method": "tools/call",
"params": {
"name": "compute_routes",
"arguments": {
"origin": {"address": "Ferry Building, San Francisco, CA"},
"destination": {"address": "Golden Gate Park, San Francisco, CA"},
"intermediate_waypoints": [
{"address": "Palace of Fine Arts, San Francisco, CA"}
],
"travel_mode": "DRIVE",
"routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
"include_polyline": true
}
},
"jsonrpc": "2.0",
"id": 1
}
پاسخ
پاسخ حاوی routes[] است که از بیشترین به کمترین توصیه مرتب شده است. فقط
یک مسیر برگردانده می‌شود مگراینکه compute_alternative_routes true باشد. هر
مسیر شامل این موارد است:
-
distanceMeters: مسافت سفر در مسیر، به متر. -
duration: زمان لازم برای طی کردن مسیر. باROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL، مدت زمان براساس وضعیت ترافیک محاسبه می‌شود. encodedPolyline: مسیر به‌عنوان چندخطی کدبندی‌شده، وقتیinclude_polylinetrueاست. می‌توانید از آن برای ترسیم مسیر روی نقشه با دیگر میاناهای برنامه‌سازی کاربردی «پلاتفرم Google Maps» استفاده کنید.-
attribution: ارجاعی که باید با مسیر نشان دهید. الزامات ذکر منبع را ببینید.
گزینه‌های Pro درطول «دسترسی عمومی محدودشده»
درطول «دسترسی عمومی محدود»، گزینه‌های Pro فقط برای پروژه‌های موجود در فهرست مجاز Pro دردسترس است. اگر پروژه‌تان هنوز در فهرست مجازها نیست:
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMALبه‌عنوانROUTING_PREFERENCE_TRAFFIC_UNAWAREدرنظر گرفته می‌شود و درخواست تحت «شناسه محصول» Essentials صورت‌حساب می‌شود.- درخواست با بیش‌از ۱۰ نقطه‌مسیر میانی خطای
INVALID_ARGUMENTرا برمی‌گرداند («حداکثر ۱۰ نقطه‌مسیر میانی پشتیبانی می‌شود»).
برای درخواست دسترسی، گزینه‌های Pro درطول «دسترسی عمومی محدودشده» را ببینید.
صورت‌حساب و سهمیه‌ها
هر درخواست compute_routes یک رویداد قابل‌صورت‌حساب است:
- درخواستی که از هیچ گزینه Pro استفاده نمی‌کند تحت شناسه محصول Essentials صورت‌حساب می‌شود.
- درخواستی که از گزینه Pro استفاده می‌کند تحت شناسه Pro صورت‌حساب می‌شود. استفاده از هر دو گزینه Pro در یک درخواست، هزینه را تغییر نمی‌دهد. برای قیمت‌گذاری Pro، به مقایسه Essentials، Pro، و «پایه‌مندسازی با Google Maps» مراجعه کنید.
درخواست کردن مسیرهای جایگزین، چندخطی، زمان حرکت یا رسیدن، یا حالت سفر متفاوت، شناسه کالا را تغییر نمی‌دهد.
سهمیه compute_routes برابر با ۳۰۰ پُرسمان در دقیقه برای هر پروژه است که بین هر دو SKU مشترک است. برای قیمت‌گذاری،
جدول قیمت‌گذاری اصلی و
جدول قیمت‌گذاری هند را ببینید.
محدودیت‌ها
- هر درخواست می‌تواند حداکثر ۲۵ نقطه‌مسیر میانی داشته باشد؛ ۱۱ تا ۲۵ گزینه Pro است. درخواست با تعداد بیشتر، خطای
INVALID_ARGUMENTرا برمی‌گرداند. - مسیرهای حمل‌ونقل عمومی از نقطه‌مسیرهای میانی پشتیبانی نمی‌کنند. درخواست حمل‌ونقل عمومی
با نقطه‌مسیرهای میانی خطای
INVALID_ARGUMENTبرمی‌گرداند. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMALبرای مسیرهای پیاده‌روی یا دوچرخه‌سواری پشتیبانی نمی‌شود.- برای مسیرهای حمل‌ونقل عمومی، زمان‌های حرکت و رسیدن می‌تواند تا ۷ روز در گذشته یا ۱۰۰ روز در آینده باشد. برای حالت‌های دیگر سفر، این زمان نمی‌تواند در گذشته باشد و می‌تواند حداکثر ۳۶۵ روز در آینده باشد.
- مختصات نقطه‌مسیر باید در محدوده جغرافیایی معتبر باشد (عرض جغرافیایی از ۹۰- تا ۹۰، طول جغرافیایی از ۱۸۰- تا ۱۸۰).
- این ابزار مراحل گام‌به‌گام، بخش‌ها، یا جزئیات خطوط حمل‌ونقل عمومی را برنمی‌گرداند.