دریافت مسیرها ازطریق 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 کارآمدترین مسیرها را برمی‌گرداند. مدت سفر عامل اصلی بهینه‌سازی است، اما 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 نشان می‌دهد که مسیر محاسبه‌شده باید از پله‌های داخلی برای مسیرهای پیاده‌روی و حمل‌ونقل عمومی اجتناب کند.

    It's possible to request a route that avoids any combination of tolls, highways and ferries by passing multiple restrictions to the avoid parameter. برای مثال: 

    avoid=tolls|highways|ferries.

  • departure_time

    زمان ترجیحی حرکت را مشخص می‌کند. می‌توانید زمان را به‌صورت عدد صحیح برحسب ثانیه از نیمه‌شب ۱ ژانویه ۱۹۷۰ (به‌وقت ساعت هماهنگ جهانی) مشخص کنید. اگر departure_time بعداز 9999-12-31T23:59:59.999999999Z مشخص شده باشد، میانای برنامه‌سازی کاربردی 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

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

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

قدم بعدی چیست

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

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