دریافت مسیرها ازطریق Directions API (قدیمی)

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

این محصول در وضعیت قدیمی است. از اکتبر ۲۰۲۶، Directions API (قدیمی) دیگر نمی‌تواند برای پروژه‌های جدید Google Cloud فعال شود. پروژه‌های موجود همچنان کاملاً پشتیبانی می‌شوند. برای ویژگی‌های جدید و عملکرد بهبودیافته، به Routes API منتقل شوید.

برای محاسبات مسیر که در زمان واقعی به ورودی کاربر پاسخ می‌دهد (برای مثال، در عنصر میانای کاربر)، می‌توانید از Directions API (قدیمی) استفاده کنید یا اگر از Maps JavaScript API استفاده می‌کنید، از سرویس Directions استفاده کنید. برای استفاده در سمت سرور، می‌توانید از Java Client،‏ Python Client،‏ Go Client، و Node.js Client برای «سرویس‌های Google Maps» استفاده کنید.

با Directions API (قدیمی)، می‌توانید:

  • مسیرها را برای چندین حالت حمل‌ونقل، ازجمله حمل‌ونقل عمومی، رانندگی، پیاده‌روی، یا دوچرخه‌سواری جستجو کنید.
  • مسیرهای چندبخشی را بااستفاده از مجموعه‌ای از نقطه‌مسیرها برمی‌گرداند.
  • مبدأ، مقصد، و نقطه‌مسیرها را به‌صورت رشته‌های نوشتاری (مثلاً «Chicago, IL» یا «Darwin, NT, Australia»)، شناسه جا، یا مختصات طول/عرض جغرافیایی مشخص کنید.

این میانای برنامه‌سازی کاربردی هنگام محاسبه مسیرها، کارآمدترین مسیرها را برمی‌گرداند. مدت سفر عامل اصلی بهینه‌سازی است، اما API ممکن است عوامل دیگری را نیز درنظر بگیرد مانند فاصله، تعداد پیچ‌ها و موارد دیگر هنگام تصمیم‌گیری درباره اینکه کدام مسیر کارآمدترین است.

قبل‌از شروع

قبل‌از شروع استفاده از Directions API (Legacy)، به پروژه‌ای با حساب صورت‌حساب و Directions API (Legacy) فعال نیاز دارید. برای کسب اطلاعات بیشتر، راه‌اندازی در کنسول Cloud را ببینید.

درخواست‌های Directions API (قدیمی) خود را بسازید

درخواست Directions API (قدیمی) به‌صورت زیر است:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

که outputFormat می‌تواند یکی از مقادیر زیر باشد:

  • json (توصیه‌شده) نشان‌دهنده خروجی در JavaScript Object Notation (JSON) است
  • xml نشان‌دهنده برونداد به‌صورت XML است

توجه: نشانی‌های وب باید به‌درستی کدبندی شده باشند تا معتبر باشند و برای همه سرویس‌های وب به ۱۶۳۸۴ نویسه محدود می‌شوند. هنگام ساختن نشانی‌های وب خود، به این محدودیت توجه داشته باشید.

همان‌طور که در نشانی‌های وب استاندارد است، همه پارامترها بااستفاده از نویسه اَمپرسند (&) از هم جدا می‌شوند. همه نویسه‌های رزروشده (برای مثال علامت جمع «+») باید کدبندی نشانی وب شوند. فهرست پارامترها و مقادیر احتمالی آن‌ها در زیر ذکر شده است.

پارامترهای الزامی

مقصد

شناسه مکان، نشانی، یا مقدار متنی طول/عرض جغرافیایی که می‌خواهید مسیرها را برای آن محاسبه کنید. گزینه‌های پارامتر مقصد همانند پارامتر مبدأ است.

منشأ

شناسه مکان، نشانی، یا مقدار متنی طول/عرض جغرافیایی که می‌خواهید مسیرها را از آنجا محاسبه کنید.

  • شناسه‌های مکان باید پیشوند place_id: داشته باشند. می‌توانید شناسه‌های جا را از Geocoding API و Places API (ازجمله «تکمیل خودکار جا») بازیابی کنید. برای نمونه‌ای از استفاده از شناسه‌های جا از «تکمیل خودکار جا»، تکمیل خودکار جا و مسیر را ببینید. برای اطلاعات بیشتر درباره شناسه‌های مکان، نمای کلی شناسه مکان را ببینید. 

    origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • اگر نشانی‌ای را ارسال کنید، سرویس «مسیرها» رشته را زمین‌کدیابی می‌کند و آن را به مختصات طول/ عرض جغرافیایی تبدیل می‌کند تا مسیرها را محاسبه کند. این مختصات ممکن است با مختصات برگردانده‌شده توسط Geocoding API متفاوت باشد، مثلاً ورودی ساختمان به‌جای مرکز آن. 

    origin=24+Sussex+Drive+Ottawa+ON

    استفاده از شناسه مکان بر استفاده از نشانی یا مختصات طول/ عرض جغرافیایی ترجیح داده می‌شود. استفاده از مختصات همیشه منجر به این می‌شود که نقطه به نزدیک‌ترین جاده به آن مختصات متصل شود - که ممکن است نقطه دسترسی به ملک نباشد، یا حتی جاده‌ای نباشد که سریع یا ایمن به مقصد برسد.

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

    origin=41.43206,-81.38992

  • Plus Code باید به‌صورت کد جهانی یا کد ترکیبی قالب‌بندی شود. Plus Code را به‌صورت نشان‌داده‌شده در اینجا قالب‌بندی کنید (علامت‌های جمع به %2B و فاصله‌ها به %20 تبدیل می‌شوند).

    • کد جهانی کد منطقه‌ای ۴ نویسه‌ای و کد محلی ۶ نویسه‌ای یا طولانی‌تر است (849VCWC8+R9 همان 849VCWC8%2BR9 است).
    • کد ترکیبی کد محلی ۶ نویسه‌ای یا طولانی‌تر با مکان صریح است (CWC8+R9 Mountain View, CA, USA ‏CWC8%2BR9%20Mountain%20View%20CA%20USA است).
توجه: برای کارایی و دقت، درصورت امکان از شناسه مکان استفاده کنید. این شناسه‌ها به‌طور منحصربه‌فردی صریح هستند، مانند جفت مقدار عرض/طول جغرافیایی، و مزایای زمین‌کدیابی را برای مسیریابی، مانند نقاط دسترسی و متغیرهای ترافیک، ارائه می‌دهند. برخلاف نشانی، شناسه‌ها برای انجام جستجو یا درخواست واسطه برای جزئیات مکان به سرویس نیاز ندارند؛ بنابراین، عملکرد بهتر است.

پارامترهای اختیاری

جایگزین‌ها

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

arrival_time

زمان ترجیحی رسیدن برای مسیرهای حمل‌ونقل عمومی را برحسب ثانیه از نیمه‌شب ۱ ژانویه ۱۹۷۰ به وقت «ساعت هماهنگ جهانی» مشخص می‌کند. می‌توانید departure_time یا arrival_time را مشخص کنید، اما نه هر دو را. توجه داشته باشید که arrival_time باید به‌عنوان عدد صحیح مشخص شود.

اجتناب کردن

نشان می‌دهد که مسیر(های) محاسبه‌شده باید از ویژگی‌های نشان‌داده‌شده اجتناب کند. این پارامتر از آرگومان‌های زیر پشتیبانی می‌کند:

  • tolls نشان می‌دهد که مسیر محاسبه‌شده باید از جاده‌ها/پل‌های عوارضی اجتناب کند.
  • highways نشان می‌دهد که مسیر محاسبه‌شده باید از بزرگراه‌ها اجتناب کند.
  • ferries نشان می‌دهد که مسیر محاسبه‌شده باید از کشتی‌های خودروبر اجتناب کند.
  • indoor نشان می‌دهد که مسیر محاسبه‌شده باید از پله‌های داخلی برای مسیرهای پیاده‌روی و حمل‌ونقل عمومی اجتناب کند.

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

avoid=tolls|highways|ferries.

departure_time

زمان ترجیحی حرکت را مشخص می‌کند. می‌توانید زمان را به‌صورت عدد صحیح برحسب ثانیه از نیمه‌شب ۱ ژانویه ۱۹۷۰ (به‌وقت ساعت هماهنگ جهانی) مشخص کنید. اگر departure_time دیرتر از 9999-12-31T23:59:59.999999999Z مشخص شده باشد، API departure_time را به 9999-12-31T23:59:59.999999999Z برمی‌گرداند. یا می‌توانید مقدار now را مشخص کنید که زمان حرکت را روی زمان کنونی (با دقت نزدیک‌ترین ثانیه) تنظیم می‌کند. زمان حرکت ممکن است در دو حالت مشخص شود:

  • برای درخواست‌هایی که حالت سفر حمل‌ونقل عمومی است: می‌توانید به‌صورت اختیاری یکی از departure_time یا arrival_time را مشخص کنید. اگر هیچ‌کدام از زمان‌ها مشخص نشده باشد، departure_time به‌طور پیش‌فرض روی زمان فعلی تنظیم می‌شود (یعنی زمان حرکت به‌طور پیش‌فرض روی زمان فعلی تنظیم می‌شود).
  • برای درخواست‌هایی که حالت سفر رانندگی است: می‌توانید departure_time را مشخص کنید تا مسیر و مدت سفر را دریافت کنید (فیلد پاسخ: duration_in_traffic) که شرایط ترافیک را درنظر می‌گیرد. departure_time باید روی زمان فعلی یا زمانی در آینده تنظیم شود. نمی‌تواند در گذشته باشد.
توجه: اگر زمان حرکت مشخص نشده باشد، انتخاب مسیر و مدت‌زمان براساس شبکه جاده‌ای و میانگین شرایط ترافیک مستقل از زمان انجام می‌شود. نتایج برای یک درخواست معین ممکن است درطول زمان به‌دلیل تغییرات در شبکه جاده‌ای، شرایط ترافیک متوسط به‌روزشده، و ماهیت توزیع‌شده سرویس متفاوت باشد. نتایج ممکن است بین مسیرهای تقریباً معادل در هر زمان یا فرکانس متفاوت باشد.
توجه: درخواست‌های Distance Matrix که departure_time را مشخص می‌کنند، وقتی mode=driving به حداکثر ۱۰۰ عنصر در هر درخواست محدود می‌شوند. تعداد مبدأها ضربدر تعداد مقصدها تعداد عناصر را تعریف می‌کند.

زبان

زبانی که نتایج به آن برگردانده می‌شود. توجه داشته باشید که این فقط برای نشانی‌های زمین‌کدیابی‌شده در start_address و end_address، نوشتار بومی‌سازی‌شده در فیلدهای distance و duration (در بخش‌ها و مراحل)، و شرح مانورها در html_instructions اعمال می‌شود، اما برای نام‌ها و نشانی‌ها در html_instructions که به زبان و خط محلی‌شان قالب‌بندی شده‌اند اعمال نمی‌شود.

  • فهرست زبان‌های پشتیبانی‌شده را ببینید. Google اغلب زبان‌های پشتیبانی‌شده را به‌روز می‌کند، بنابراین این فهرست ممکن است جامع نباشد.
  • اگر language ارائه نشده باشد، API تلاش می‌کند از زبان ترجیحی مشخص‌شده در سرصفحه Accept-Language استفاده کند.
  • این API تمام تلاش خود را می‌کند تا نشانی خیابانی ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل‌خواندن باشد. برای دستیابی به این هدف، نشانی‌های خیابان را به زبان محلی برمی‌گرداند و درصورت لزوم، با رعایت زبان ترجیحی، آن‌ها را به نویسه‌ای که برای کاربر خوانا باشد نویسه‌گردانی می‌کند. همه نشانی‌های دیگر به زبان ترجیحی برگردانده می‌شوند. همه مؤلفه‌های نشانی به همان زبانی برگردانده می‌شوند که از مؤلفه اول انتخاب شده است.
  • اگر نامی به زبان ترجیحی دردسترس نباشد، API از نزدیک‌ترین مطابقت استفاده می‌کند.
  • زبان ترجیحی تأثیر کمی بر مجموعه نتایجی دارد که میانای برنامه‌سازی کاربردی برای برگرداندن انتخاب می‌کند و ترتیبی که برگردانده می‌شوند. زمین‌کدیاب اختصارات را بسته به زبان به‌طور متفاوتی تفسیر می‌کند، مانند اختصارات برای انواع خیابان‌ها، یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند. برای مثال، utca و tér در زبان مجاری مترادف خیابان هستند.

حالت حمل‌ونقل

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

  • driving (پیش‌فرض) نشان‌دهنده مسیرهای رانندگی استاندارد یا مسافت بااستفاده از شبکه جاده‌ای است.
  • walking درخواست مسیر پیاده‌روی یا مسافت ازطریق مسیرهای عابر پیاده و پیاده‌روها (درصورت وجود).
  • bicycling درخواست مسیرهای دوچرخه‌سواری یا فاصله ازطریق مسیرهای دوچرخه و خیابان‌های ترجیحی (درصورت وجود) می‌کند.
  • transit بااستفاده از مسیرهای حمل‌ونقل عمومی (درصورت دردسترس بودن) درخواست مسیر یا فاصله می‌کند. اگر حالت را روی حمل‌ونقل عمومی تنظیم کنید، می‌توانید به‌صورت اختیاری departure_time یا arrival_time را مشخص کنید. اگر هیچ‌کدام از زمان‌ها مشخص نشده باشد، departure_time به‌طور پیش‌فرض روی زمان فعلی تنظیم می‌شود (یعنی زمان حرکت به‌طور پیش‌فرض روی زمان فعلی تنظیم می‌شود). همچنین می‌توانید به‌صورت اختیاری یک transit_mode و/یا یک transit_routing_preference اضافه کنید. سفرهای حمل‌ونقل عمومی تا ۷ روز در گذشته یا تا ۱۰۰ روز در آینده دردسترس است، مشروط به دردسترس بودن اطلاعات حمل‌ونقل عمومی ارائه‌شده توسط ارائه‌دهندگان داده. برنامه‌های زمانی حمل‌ونقل عمومی مرتباً تغییر می‌کنند، سفرهای حمل‌ونقل عمومی دردسترس ممکن است درطول زمان تغییر کنند و هیچ تضمینی برای ارائه نتایج یکسان برای پیش‌بینی‌های خیلی زودتر از موعد وجود ندارد.
توجه: گاهی اوقات ممکن است مسیرهای پیاده‌روی و دوچرخه‌سواری شامل مسیرهای واضح برای عابران پیاده یا دوچرخه‌سواران نباشند، بنابراین این مسیرها در نتیجه بازگردانده‌شده هشدارهایی را برمی‌گردانند که باید به کاربر نمایش دهید.

منطقه

کد منطقه، که به‌عنوان یک مقدار دو نویسه‌ای ccTLD («دامنه سطح بالا») مشخص شده است. اکثر کدهای ccTLD با کدهای ISO 3166-1 یکسان هستند، با چند استثنای قابل‌توجه. برای مثال، دامنه سطح بالای کد کشور پادشاهی متحد «uk»‏ (co.uk.) است، درحالی‌که کد ISO 3166-1 آن «gb» است (ازنظر فنی برای نهاد «پادشاهی متحد بریتانیای کبیر و ایرلند شمالی»).

traffic_model

فرض‌های مورد استفاده هنگام محاسبه زمان در ترافیک را مشخص می‌کند. این تنظیم بر مقدار برگردانده‌شده در فیلد duration_in_traffic در پاسخ تأثیر می‌گذارد، که حاوی زمان پیش‌بینی‌شده در ترافیک براساس میانگین‌های گذشته است. پارامتر traffic_model فقط برای مسیرهای رانندگی که درخواست شامل departure_time باشد مشخص می‌شود. مقادیر دردسترس برای این پارامتر عبارت‌اند از:

  • best_guess (پیش‌فرض) نشان می‌دهد که duration_in_traffic برگردانده‌شده باید بهترین تخمین از مدت سفر باشد که براساس اطلاعات موجود درباره شرایط ترافیک گذشته و ترافیک زنده ارائه شده است. هرچه departure_time به زمان فعلی نزدیک‌تر باشد، ترافیک زنده اهمیت بیشتری پیدا می‌کند.
  • pessimistic نشان می‌دهد که duration_in_traffic برگردانده‌شده باید در اکثر روزها طولانی‌تر از مدت سفر واقعی باشد، هرچند ممکن است در روزهایی که شرایط ترافیک به‌طور خاص بد است، این مقدار بیشتر شود.
  • optimistic نشان می‌دهد که duration_in_traffic برگردانده‌شده باید در اکثر روزها کوتاه‌تر از مدت سفر واقعی باشد، هرچند در روزهای خاصی که شرایط ترافیک بسیار خوب است ممکن است سریع‌تر از این مقدار باشد.

مقدار پیش‌فرض best_guess مفیدترین پیش‌بینی‌ها را برای اکثر موارد استفاده ارائه می‌دهد. ممکن است best_guess پیش‌بینی زمان سفر کوتاه‌تر از optimistic، یا برعکس، طولانی‌تر از pessimistic باشد، به‌دلیل روشی که best_guess مدل پیش‌بینی اطلاعات ترافیک زنده را ادغام می‌کند.

transit_mode

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

  • bus نشان می‌دهد که مسیر محاسبه‌شده باید سفر با اتوبوس را ترجیح دهد.
  • subway نشان می‌دهد که مسیر محاسبه‌شده باید سفر با مترو را ترجیح دهد.
  • train نشان می‌دهد که مسیر محاسبه‌شده باید سفر با قطار را ترجیح دهد.
  • tram نشان می‌دهد که مسیر محاسبه‌شده باید سفر با تراموا و قطار شهری را ترجیح دهد.
  • rail نشان می‌دهد که مسیر محاسبه‌شده باید ترجیحاً با قطار، تراموا، قطار شهری، و مترو باشد. این معادل transit_mode=train|tram|subway است.

transit_routing_preference

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

  • less_walking نشان می‌دهد که مسیر محاسبه‌شده باید پیاده‌روی محدود را ترجیح دهد.
  • fewer_transfers نشان می‌دهد که مسیر محاسبه‌شده باید تعداد محدودی تعویض وسیله داشته باشد.

واحدها

سیستم واحدی را که باید هنگام نمایش نتایج استفاده شود مشخص می‌کند.

نتایج مسیرها حاوی نوشتاری در فیلدهای فاصله است که ممکن است برای نشان دادن فاصله «مرحله» خاصی از مسیر به کاربر نمایش داده شود. به‌طور پیش‌فرض، این نوشتار از سیستم واحد کشور یا منطقه مبدأ استفاده می‌کند.

برای مثال، مسیری از «شیکاگو، ایلینوی» به «تورنتو، انتاریو» نتایج را به مایل نشان می‌دهد، درحالی‌که مسیر برعکس نتایج را به کیلومتر نشان می‌دهد. می‌توانید این سیستم واحد را با تنظیم صریح یک سیستم واحد در پارامتر واحدهای درخواست و ارسال یکی از مقادیر زیر لغو کنید:

  • metric استفاده از سیستم متریک را مشخص می‌کند. فاصله‌های متنی بااستفاده از کیلومتر و متر برگردانده می‌شود.
  • imperial استفاده از سیستم امپریال (انگلیسی) را مشخص می‌کند. مسافت‌های متنی بااستفاده از مایل و فوت برگردانده می‌شود.
توجه: این تنظیم سیستم واحد فقط بر نوشتار نمایش‌داده‌شده در فیلدهای فاصله تأثیر می‌گذارد. فیلدهای فاصله نیز حاوی مقادیری هستند که همیشه به متر بیان می‌شوند.

نقطه‌مسیرها

احتیاط: درخواست‌هایی که از بیش‌از ۱۰ نقطه‌مسیر (بین ۱۱ تا ۲۵) یا بهینه‌سازی نقطه‌مسیر استفاده می‌کنند، با نرخ بالاتری صورت‌حساب می‌شوند. درباره صورت‌حساب محصولات Google Maps Platform بیشتر بدانید.

آرایه‌ای از مکان‌های میانی را برای گنجاندن در طول مسیر بین مبدأ و مقصد به‌عنوان مکان‌های عبوری یا توقفگاه مشخص می‌کند. نقطه‌مسیرها با هدایت کردن مسیر ازطریق مکان(های) مشخص‌شده، آن را تغییر می‌دهند. این API از نقاط‌مسیر برای این حالت‌های سفر پشتیبانی می‌کند: رانندگی، پیاده‌روی، و دوچرخه‌سواری؛ نه حمل‌ونقل عمومی. می‌توانید یک یا چند مکان را که با نویسه خط عمودی (| یا %7C) از هم جدا شده‌اند به‌صورت شناسه مکان، نشانی، یا مختصات طول/عرض جغرافیایی ارائه دهید. به‌طور پیش‌فرض، سرویس «مسیرها» مسیر را بااستفاده از نقاط‌مسیر به‌ترتیبی که ارائه شده‌اند محاسبه می‌کند. اولویت تجزیه مقدار نقطه‌مسیر عبارت است از شناسه مکان، مختصات عرض جغرافیایی/ طول جغرافیایی، و سپس نشانی.

  • اگر شناسه مکانی را ارسال می‌کنید، باید پیشوند place_id: را به آن اضافه کنید. می‌توانید شناسه‌های جا را از Geocoding API و Places API (ازجمله «تکمیل خودکار جا») بازیابی کنید. برای نمونه‌ای از استفاده از شناسه‌های جا از «تکمیل خودکار جا»، تکمیل خودکار جا و مسیرها را ببینید. برای اطلاعات بیشتر درباره شناسه‌های مکان، نمای کلی شناسه مکان را ببینید.
    برای کارایی و دقت، درصورت امکان از شناسه مکان استفاده کنید. این شناسه‌ها به‌طور منحصربه‌فردی صریح هستند، مانند جفت مقدار عرض/طول جغرافیایی، و مزایای زمین‌کدیابی را برای مسیریابی، مانند نقاط دسترسی و متغیرهای ترافیک، فراهم می‌کنند. برخلاف نشانی، شناسه‌ها برای انجام جستجو یا درخواست واسطه برای جزئیات مکان به سرویس نیاز ندارند؛ بنابراین، عملکرد بهتر است.
  • اگر مختصات عرض جغرافیایی/طول جغرافیایی را ارسال کنید، مقادیر مستقیماً به سرور پیشانه می‌روند تا مسیرها را بدون زمین‌کدیابی محاسبه کنند. نقاط به جاده‌ها هم‌تراز می‌شوند و ممکن است دقت موردنیاز برنامه‌تان را ارائه ندهند. وقتی مطمئن هستید که مقادیر واقعاً نقاطی را که برنامه‌تان برای مسیریابی نیاز دارد مشخص می‌کنند، از مختصات استفاده کنید، بدون توجه به نقاط دسترسی احتمالی یا جزئیات زمین‌کدیابی اضافی. مطمئن شوید که مقادیر طول و عرض جغرافیایی با ویرگول (%2C) و نه فاصله (%20) از هم جدا شده باشند.
  • اگر نشانی‌ای را ارسال کنید، سرویس «مسیرها» رشته را زمین‌کدیابی می‌کند و آن را به مختصات طول/عرض جغرافیایی تبدیل می‌کند تا مسیرها را محاسبه کند. اگر مقدار نشانی مبهم باشد، ممکن است این مقدار باعث شود جستجویی برای رفع ابهام از نشانی‌های مشابه انجام شود. برای مثال، «خیابان اول» می‌تواند مقدار کامل یا مقدار جزئی برای «خیابان اول شمال شرقی» یا «خیابان اول جنوب شرقی» باشد. این نتیجه ممکن است با نتیجه‌ای که Geocoding API برمی‌گرداند متفاوت باشد. بااستفاده از شناسه مکان می‌توانید از سوءتعبیرهای احتمالی جلوگیری کنید.
  • یا می‌توانید مجموعه‌ای از نقاط کدگذاری‌شده را بااستفاده از الگوریتم چندخطی کدگذاری‌شده ارائه دهید. خواهید دید که مجموعه کدگذاری‌شده برای تعداد زیادی از نقاط مسیر مفید است، زیرا نشانی وب به‌طور قابل‌توجهی کوتاه‌تر است. همه سرویس‌های وب دارای محدودیت نشانی وب ۱۶۳۸۴ نویسه هستند.
    • چندخطی‌های کدبندی‌شده باید پیشوند enc: داشته باشند و به‌دنبال آن دونقطه (:) بیاید. برای مثال: waypoints=enc:gfo}EtohhU:.
    • همچنین می‌توانید چند چندخطی کدبندی‌شده را که با نویسه پایپ (|) از هم جدا شده‌اند اضافه کنید. برای مثال، waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:| via:enc:udymA{~bxM:

تأثیر گذاشتن بر مسیرها با نقاط بین‌راهی توقف و عبور

برای هر نقطه‌مسیر در درخواست، پاسخ مسیرها ورودی‌ای به آرایه legs اضافه می‌کند تا جزئیات توقف‌های بین راه را در آن بخش از سفر ارائه دهد.

اگر می‌خواهید بااستفاده از نقطه‌مسیرها بر مسیر تأثیر بگذارید بدون اینکه توقف بین راهی اضافه کنید، پیشوند via: را به نقطه‌مسیر اضافه کنید. نقاط‌مسیر با پیشوند via: ورودی‌ای به آرایه legs اضافه نمی‌کنند، اما سفر را ازطریق نقطه مسیر هدایت می‌کنند.

نشانی وب زیر درخواست قبلی را به‌گونه‌ای اصلاح می‌کند که مسیر سفر ازطریق لکسینگتون بدون توقف مسیریابی می‌شود: 

https://maps.googleapis.com/maps/api/directions/json?
origin=Boston,MA&destination=Concord,MA
&waypoints=Charlestown,MA|via:Lexington,MA

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

احتیاط: استفاده از پیشوند via: برای اجتناب از توقف‌های بین‌راهی منجر به مسیرهایی می‌شود که در تفسیر نقطه‌مسیر سخت‌گیرانه هستند. این تفسیر ممکن است منجر به انحراف‌های شدید در مسیر یا ZERO_RESULTS در کد وضعیت پاسخ شود، اگر Directions API نتواند مسیرها را ازطریق آن نقطه ایجاد کند.

بهینه‌سازی نقاط‌مسیر

به‌طور پیش‌فرض، سرویس «مسیرها» مسیری را ازطریق نقاط‌مسیر ارائه‌شده به‌ترتیب داده‌شده محاسبه می‌کند. درصورت تمایل، می‌توانید optimize:true را به‌عنوان اولین آرگومان در پارامتر نقاط‌مسیر ارسال کنید تا به سرویس «مسیرها» اجازه دهید با مرتب کردن مجدد نقاط‌مسیر به ترتیبی کارآمدتر، مسیر ارائه‌شده را بهینه‌سازی کند. (این بهینه‌سازی کاربردی از مسئله فروشنده دوره‌گرد است.) مدت سفر عامل اصلی است که بهینه‌سازی می‌شود، اما عوامل دیگری مانند مسافت، تعداد پیچ‌ها و موارد دیگر ممکن است هنگام تصمیم‌گیری درباره اینکه کدام مسیر کارآمدترین است درنظر گرفته شود. همه نقاط‌مسیر باید توقفگاه باشند تا سرویس «مسیرها» بتواند مسیر آن‌ها را بهینه‌سازی کند.

اگر به سرویس «مسیرها» دستور دهید ترتیب نقاط‌مسیر را بهینه‌سازی کند، ترتیب آن‌ها در فیلد waypoint_order در شیء مسیرها برگردانده خواهد شد. فیلد waypoint_order مقادیری را برمی‌گرداند که صفرپایه هستند.

مثال زیر سفر جاده‌ای از آدلاید، استرالیای جنوبی به هریک از مناطق اصلی شراب‌سازی استرالیای جنوبی را بااستفاده از بهینه‌سازی مسیر محاسبه می‌کند. 

https://maps.googleapis.com/maps/api/directions/json?
origin=Adelaide,SA&destination=Adelaide,SA
&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA

Inspection of the calculated route will indicate that calculation uses waypoints in the following waypoint order: 

"waypoint_order": [ 3, 2, 0, 1 ]
احتیاط: درخواست‌هایی که از بهینه‌سازی نقطه‌مسیر استفاده می‌کنند با نرخ بالاتری صورت‌حساب می‌شوند. درباره نحوه صدور صورت‌حساب برای محصولات Google Maps Platform بیشتر بدانید.

قدم بعدی چیست

نمونه‌های مسیرها

پاسخ‌های مسیر