برای محاسبه مسیر، باید حداقل مکان‌های مبدأ و مقصد مسیر را مشخص کنید. این مکان‌ها را به‌عنوان نقطه‌مسیر در مسیر تعریف می‌کنید.
علاوه‌بر مبدأ و مقصد، می‌توانید انواع مختلفی از نقطه‌مسیرها و نحوه مدیریت نقطه‌مسیرها را برای یک مسیر مشخص کنید. برای اطلاعات بیشتر و نمونه‌ها، این موضوعات را ببینید:
- مشخص کردن جهت خودرو و سمت جاده
- مشخص کردن نقطه‌مسیرهای میانی
- تنظیم توقف درطول مسیر
- تنظیم نقطه‌ای برای عبور مسیر
- بهینه‌سازی ترتیب ایستگاه‌ها در مسیر
مشخص کردن مکان‌ها برای مسیر
با ایجاد شیء نقطه‌مسیر (REST) یا نقطه‌مسیر (gRPC)، مکانی را نشان می‌دهید. در تعریف نقطه‌مسیر، می‌توانید مکان را به یکی از روش‌های زیر مشخص کنید:
- شناسه مکان (ترجیحی)
- مختصات طول/عرض جغرافیایی
- رشته نشانی («Chicago, IL» یا «Darwin, NT, Australia»)
- کد نقطه پیمایش
- Plus Code
می‌توانید مکان‌ها را برای همه نقطه‌مسیرها در یک درخواست به همان روش مشخص کنید، یا می‌توانید آن‌ها را ترکیب کنید. برای مثال، می‌توانید از مختصات طول/عرض جغرافیایی برای نقطه‌مسیر مبدأ و از شناسه مکان برای نقطه‌مسیر مقصد استفاده کنید.
برای کارایی و دقت، به‌جای مختصات طول/عرض جغرافیایی یا رشته‌های نشانی، از شناسه مکان استفاده کنید. «شناسه‌های مکان» به‌طور منحصربه‌فردی صریح هستند و مزایای زمین‌کدیابی را برای مسیریابی، مانند نقاط دسترسی و متغیرهای ترافیک، ارائه می‌دهند. این روش‌ها کمک می‌کنند از موقعیت‌های زیر که ممکن است درنتیجه روش‌های دیگر مشخص کردن مکان ایجاد شوند اجتناب کنید:
- استفاده از مختصات طول/ عرض جغرافیایی می‌تواند باعث شود مکان به نزدیک‌ترین جاده به آن مختصات متصل شود - که ممکن است نقطه دسترسی به ملک نباشد، یا حتی جاده‌ای نباشد که سریع یا ایمن به مقصد منتهی شود.
- رشته‌های نشانی ابتدا باید توسط Routes API زمین‌کدیابی شوند تا قبل‌از محاسبه مسیر، به مختصات عرض جغرافیایی/طول جغرافیایی تبدیل شوند. این تبدیل می‌تواند بر عملکرد تأثیر بگذارد.
مشخص کردن مکان به‌عنوان شناسه جا
می‌توانید از شناسه مکان برای مشخص کردن مکان نقطه‌مسیر استفاده کنید. چون مختصات طول و عرض جغرافیایی به جاده‌ها هم‌تراز می‌شوند، ممکن است متوجه شوید که شناسه مکان در برخی شرایط نتایج بهتری ارائه می‌دهد.
شناسه‌های جا را از Geocoding API و Places API (New) (شامل Autocomplete (New)) بازیابی کنید. برای اطلاعات بیشتر درباره شناسه‌های مکان، نمای کلی شناسه مکان را ببینید.
مثال زیر از ویژگی placeId برای ارسال شناسه مکان برای هر دو
origin و destination استفاده می‌کند:
{ "origin":{ "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o" }, "destination":{ "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU" }, ... }
مکان را به‌صورت مختصات طول و عرض جغرافیایی مشخص کنید
برای تعریف مکان در نقطه‌مسیر، مکان (REST) یا مکان (gRPC) را بااستفاده از مختصات طول/ عرض جغرافیایی مشخص کنید.
برای مثال، نقطه‌مسیر را برای مسیر origin و destination
بااستفاده از مختصات latitude و longitude مشخص کنید:
{ "origin":{ "location":{ "latLng":{ "latitude": 37.419734, "longitude": -122.0827784 } } }, "destination":{ "location":{ "latLng":{ "latitude": 37.417670, "longitude": -122.079595 } } }, ... }
مکان را به‌صورت رشته نشانی مشخص کنید
رشته‌های نشانی، نشانی‌های تحت‌اللفظی هستند که با رشته نشان داده می‌شوند (مثل «1600 Amphitheatre Parkway, Mountain View, CA»). زمین‌کدیابی فرایند تبدیل رشته نشانی به مختصات عرض جغرافیایی و طول جغرافیایی است (مانند عرض جغرافیایی ۳۷٫۴۲۳۰۲۱ و طول جغرافیایی ۱۲۲٫۰۸۳۷۳۹-).
وقتی رشته نشانی را به‌عنوان مکان نقطه‌مسیر ارسال می‌کنید، Routes API رشته را به‌طور داخلی زمین‌کدیابی می‌کند تا آن را به مختصات عرض جغرافیایی و طول جغرافیایی تبدیل کند.
برای مثال، برای محاسبه مسیری که نقطه‌مسیر را برای مسیر origin و
destination بااستفاده از رشته‌های نشانی مشخص می‌کنید:
{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "450 Serra Mall, Stanford, CA 94305, USA" }, ... }
در این مثال، Routes API هر دو نشانی را زمین‌کدیابی می‌کند تا آن‌ها را به مختصات طول و عرض جغرافیایی تبدیل کند.
اگر مقدار نشانی مبهم باشد، Routes API ممکن است جستجویی را برای رفع ابهام از نشانی‌های مشابه فراخوانی کند. برای مثال، «خیابان اول» می‌تواند مقدار کامل یا مقدار جزئی برای «خیابان اول شمال شرقی» یا «خیابان اول جنوب شرقی» باشد. این نتیجه ممکن است با نتیجه‌ای که Geocoding API برمی‌گرداند متفاوت باشد. بااستفاده از شناسه‌های مکان می‌توانید از سوءتعبیرهای احتمالی جلوگیری کنید.
تنظیم منطقه برای نشانی
اگر رشته نشانی ناقصی را به‌عنوان مکان نقطه‌مسیر ارسال کنید، ممکن است میانای برنامه‌سازی کاربردی از مختصات عرض جغرافیایی/طول جغرافیایی زمین‌کدیابی‌شده اشتباهی استفاده کند. برای مثال، درخواستی ارسال می‌کنید که در آن «تولدو» به‌عنوان مبدأ و «مادرید» به‌عنوان مقصد برای مسیر رانندگی مشخص شده است:
{ "origin":{ "address": "Toledo" }, "destination":{ "address": "Madrid" }, "travelMode": "DRIVE" }
در این مثال، «تولدو» به‌عنوان شهری در ایالت اوهایو در ایالات متحده تفسیر می‌شود، نه در اسپانیا. بنابراین، درخواست یک آرایه خالی برمی‌گرداند، به این معنی که هیچ مسیری وجود ندارد:
{ [] }
می‌توانید میانای برنامه‌سازی کاربردی را پیکربندی کنید تا نتایج را با سوگیری نسبت به منطقه‌ای خاص برگرداند.
برای این کار، پارامتر regionCode را اضافه کنید. این پارامتر کد منطقه را به‌عنوان مقدار دو نویسه‌ای
ccTLD («دامنه سطح بالا»)
مشخص می‌کند. اکثر کدهای ccTLD با کدهای ISO 3166-1 یکسان هستند، با
چند استثنای قابل‌توجه. برای مثال، دامنه سطح بالای کد کشور پادشاهی متحد «uk» است (.co.uk) درحالی‌که کد ISO 3166-1 آن «gb» است (ازنظر فنی برای نهاد «پادشاهی متحد بریتانیای کبیر و ایرلند شمالی»).
درخواست مسیر برای «تولدو» به «مادرید» که شامل پارامتر regionCode است، نتایج مناسبی را برمی‌گرداند زیرا «تولدو» به‌عنوان شهری در اسپانیا تفسیر می‌شود:
{ "origin":{ "address": "Toledo" }, "destination":{ "address": "Madrid" }, "travelMode": "DRIVE", "regionCode": "es" }
اکنون پاسخ حاوی مسیر محاسبه‌شده از تولدو، اسپانیا به مادرید، اسپانیا است:
{ "routes": [ { "distanceMeters": 75330, "duration": "4137s", ... } ] }
مشخص کردن مکان به‌عنوان نشانه نقطه پیمایش
نشان نقطه ناوبری رشته‌ای است که مکان و بافت مسیر اضافی را کدگذاری می‌کند. ژتون‌های نقطه پیمایش می‌توانند مسیریابی دقیقی به نقاط دسترسی خاص در نزدیکی ورودی‌ها، سکوهای بارگیری، یا مناطق تعیین‌شده برای سوار کردن مسافر ارائه دهند. این ویژگی در مواردی مانند ارسال غذا یا سفر اشتراکی که ممکن است نقطه سوار شدن یا پیاده شدن مبهم باشد مفید است.
می‌توانید با فراخوانی روش «مقصدها» در Geocoding API، یک کد نقطه ناوبری دریافت کنید.
برای مشخص کردن یک توکن نقطه ناوبری:
navigationPointTokenرا از روشSearchDestinationsدر Geocoding API دریافت کنید. برای اطلاعات بیشتر، به مستندات Geocoding API مراجعه کنید.- با ارسال
navigationPointToken، یک «نقطه‌مسیر» ایجاد کنید.
مثال زیر از ویژگی navigation_point_token برای ارسال یک توکن نقطه پیمایش برای هر دو origin و destination استفاده می‌کند:
{ "origin":{ "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_ORIGIN" }, "destination":{ "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_DESTINATION" }, ... }
مشخص کردن مکان به‌عنوان Plus Code
بسیاری از افراد نشانی دقیقی ندارند و این امر می‌تواند دریافت مرسوله‌ها را برای آن‌ها دشوار کند. یا افرادی که نشانی دارند ممکن است ترجیح دهند مرسوله‌ها را در مکان‌های مشخص‌تری مثل ورودی پشتی یا سکوی بارگیری تحویل بگیرند.
Plus Codes مانند نشانی خیابان برای افراد یا مکان‌هایی است که نشانی واقعی ندارند. Plus Code به‌جای نشانی با نام خیابان و شماره، براساس مختصات طول/ عرض جغرافیایی است و به‌صورت عدد و حرف نمایش داده می‌شود.
Google Plus Codes را توسعه داده است تا همه افراد و چیزها بتوانند از مزایای آدرس بهره‌مند شوند. Plus Code مرجع مکان کدگذاری‌شده‌ای است که از مختصات طول/عرض جغرافیایی مشتق شده است و منطقه‌ای را نشان می‌دهد: ۱/۸۰۰۰ درجه در ۱/۸۰۰۰ درجه (حدود ۱۴ متر در ۱۴ متر در خط استوا) یا کوچک‌تر. می‌توانید از Plus Codes به‌عنوان جایگزینی برای نشانی خیابان در مکان‌هایی که نشانی خیابان وجود ندارد یا ساختمان‌ها شماره‌گذاری نشده‌اند یا خیابان‌ها نام‌گذاری نشده‌اند استفاده کنید.
Plus Code باید به‌صورت کد جهانی یا کد ترکیبی قالب‌بندی شود:
- کد جهانی از یک پیش‌شماره ۴ نویسه‌ای و یک کد محلی ۶ نویسه‌ای یا طولانی‌تر تشکیل شده است.
برای مثال، برای نشانی «1600 Amphitheatre Parkway, Mountain View, CA»، کد جهانی «849V» و کد محلی «CWC8+R9» است. سپس از کل Plus Code ۱۰ نویسه‌ای برای مشخص کردن مقدار مکان به‌صورت «849VCWC8+R9» استفاده می‌کنید.
- کد مرکب از یک کد محلی ۶ نویسه‌ای یا طولانی‌تر
ترکیب‌شده با یک مکان صریح تشکیل شده است.
برای مثال، نشانی «450 Serra Mall, Stanford, CA 94305, USA» کد محلی «CRHJ+C3» دارد. برای نشانی ترکیبی، کد محلی را با شهر، ایالت، کد پستی، و بخش کشور نشانی به‌صورت «CRHJ+C3 Stanford, CA 94305, USA» ترکیب کنید.
برای مثال، با مشخص کردن نقطه‌مسیر برای مسیر
originوdestinationبااستفاده از Plus Codes، مسیری را محاسبه کنید:{ "origin":{ "address": "849VCWC8+R9" }, "destination":{ "address": "CRHJ+C3 Stanford, CA 94305, USA" }, "travelMode": "DRIVE" }
Plus Codes در میاناهای برنامه‌سازی کاربردی Google Maps Platform پشتیبانی می‌شود، ازجمله تکمیل خودکار (جدید)، جزئیات جا (جدید)، و Geocoding API. برای مثال، می‌توانید از Geocoding API برای زمین‌کدیابی معکوس مکانی که با مختصات عرض جغرافیایی/طول جغرافیایی مشخص شده است استفاده کنید تا Plus Code آن مکان را تعیین کنید.