برای محاسبه ماتریس مسیر، باید حداقل مکان‌های یک مبدأ مسیر و یک مقصد مسیر را مشخص کنید.
مشخص کردن مکان‌ها برای مسیر
با ایجاد شیء نقطه‌مسیر (REST) یا نقطه‌مسیر (gRPC) مکان را نشان می‌دهید. در تعریف ایستگاه بین راهی، می‌توانید مکان را به یکی از روش‌های زیر مشخص کنید:
- شناسه مکان (ترجیحی)
- مختصات طول/عرض جغرافیایی
- رشته نشانی («شیکاگو، ایلینوی» یا «داروین، قلمرو شمالی، استرالیا»)
- کد نقطه پیمایش
- کد پلاس
می‌توانید مکان‌ها را برای همه ایستگاه‌های بین راه در یک درخواست به یک روش مشخص کنید، یا می‌توانید آن‌ها را ترکیب کنید. برای مثال، می‌توانید از مختصات طول/عرض جغرافیایی برای ایستگاه بین راهی مبدأ و از شناسه مکان برای ایستگاه بین راهی مقصد استفاده کنید.
برای کارایی و دقت، به‌جای مختصات طول/عرض جغرافیایی یا رشته‌های نشانی، از شناسه‌های مکان استفاده کنید. «شناسه‌های مکان» به‌طور منحصربه‌فردی صریح هستند و مزایای زمین‌کدیابی را برای مسیریابی، مانند نقاط دسترسی و متغیرهای ترافیک، ارائه می‌دهند. این کدها به جلوگیری از موقعیت‌های زیر که ممکن است از روش‌های دیگر مشخص کردن مکان ناشی شود کمک می‌کنند:
- استفاده از مختصات طول/عرض جغرافیایی می‌تواند باعث شود مکان به نزدیک‌ترین جاده به آن مختصات منطبق شود - که ممکن است نقطه دسترسی به ملک نباشد، یا حتی جاده‌ای نباشد که سریع یا ایمن به مقصد منتهی شود.
- رشته‌های نشانی ابتدا باید توسط «میانای برنامه‌سازی کاربردی مسیرها» زمین‌کدگذاری شوند تا به مختصات عرض/طول جغرافیایی تبدیل شوند و سپس بتواند مسیر را محاسبه کند. این تبدیل می‌تواند بر عملکرد تأثیر بگذارد.
مکان را به‌عنوان شناسه مکان مشخص کنید
می‌توانید از شناسه مکان برای مشخص کردن مکان نقطه‌مسیر استفاده کنید. چون مختصات طول و عرض جغرافیایی به جاده‌ها چسبانده می‌شود، ممکن است متوجه شوید که شناسه مکان در برخی شرایط نتایج بهتری ارائه می‌دهد.
شناسه‌های مکان را از Geocoding API و Places API (جدید) (ازجمله «تکمیل خودکار (جدید)») بازیابی کنید. برای اطلاعات بیشتر درباره شناسه‌های مکان، به نمای کلی شناسه مکان مراجعه کنید.
مثال زیر از دارایی 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»). «زمین‌کدگذاری» فرایند تبدیل رشته نشانی به مختصات عرض و طول جغرافیایی (مثل عرض جغرافیایی ۳۷٫۴۲۳۰۲۱ و طول جغرافیایی ۱۲۲٫۰۸۳۷۳۹-) است.
وقتی رشته نشانی را به‌عنوان مکان ایستگاه بین راهی ارسال می‌کنید، «میانای برنامه‌سازی کاربردی مسیرها» به‌طور داخلی رشته را زمین‌کدگذاری می‌کند تا آن را به مختصات عرض و طول جغرافیایی تبدیل کند.
برای مثال، برای محاسبه مسیر، نقطه واسطی را برای مسیر origin و
destination بااستفاده از رشته‌های نشانی مشخص می‌کنید:
{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "450 Serra Mall, Stanford, CA 94305, USA" }, ... }
در این مثال، «میانای برنامه‌سازی کاربردی مسیرها» هر دو نشانی را زمین‌کد می‌کند تا آن‌ها را به مختصات عرض و طول جغرافیایی تبدیل کند.
اگر مقدار نشانی مبهم باشد، «میانای برنامه‌سازی کاربردی مسیرها» ممکن است جستجویی را برای رفع ابهام از نشانی‌های مشابه فراخوانی کند. برای مثال، «خیابان اول» می‌تواند مقدار کامل یا مقدار جزئی برای «خیابان اول شمال شرقی» یا «خیابان اول جنوب شرقی» باشد. این نتیجه ممکن است با نتیجه‌ای که Geocoding API برمی‌گرداند متفاوت باشد. بااستفاده از شناسه‌های مکان می‌توانید از سوءتعبیرهای احتمالی جلوگیری کنید.
تنظیم منطقه برای نشانی
اگر رشته نشانی ناقصی را به‌عنوان مکان ایستگاه بین راهی ارسال کنید، ممکن است «میانای برنامه‌سازی کاربردی» از مختصات عرض جغرافیایی/طول جغرافیایی زمین‌کدشده اشتباه استفاده کند. برای مثال، درخواستی می‌کنید که در آن «تولدو» را به‌عنوان مبدأ و «مادرید» را به‌عنوان مقصد مسیر رانندگی مشخص می‌کنید:
{ "origin":{ "address": "Toledo" }, "destination":{ "address": "Madrid" }, "travelMode": "DRIVE" }
در این مثال، «تولدو» به‌عنوان شهری در ایالت اوهایو در ایالات متحده تفسیر می‌شود، نه در اسپانیا. بنابراین، درخواست آرایه خالی برمی‌گرداند، یعنی هیچ مسیری وجود ندارد:
{ [] }
می‌توانید میانای برنامه‌سازی کاربردی را پیکربندی کنید تا با افزودن پارامتر regionCode نتایج را به‌نفع منطقه خاصی برگرداند. این پارامتر کد منطقه را به‌عنوان مقدار دو نویسه‌ای
ccTLD («دامنه سطح بالا»)
مشخص می‌کند. اکثر کدهای ccTLD با کدهای ISO 3166-1 یکسان هستند، با
برخی استثنائات قابل‌توجه. برای مثال، ccTLD پادشاهی متحد بریتانیای کبیر و ایرلند شمالی «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
بسیاری از افراد نشانی دقیق ندارند، که می‌تواند دریافت محموله‌ها را برای آن‌ها دشوار کند. یا، افراد دارای نشانی ممکن است ترجیح دهند محموله‌ها را در مکان‌های دقیق‌تری، مثل ورودی پشتی یا بارانداز بارگیری، تحویل بگیرند.
«کدهای باز» مانند نشانی خیابان برای افراد یا مکان‌هایی هستند که نشانی واقعی ندارند. به‌جای نشانی‌های دارای نام خیابان و شماره، «کدهای پلاس» براساس مختصات طول/عرض جغرافیایی هستند و به‌صورت اعداد و حروف نمایش داده می‌شوند.
Google کدهای پلاس را توسعه داده است تا مزایای نشانی را برای همه و همه چیز فراهم کند. «کد پستی پلاس» یک مرجع مکان کدبندی‌شده است که از مختصات طول/عرض جغرافیایی استخراج می‌شود و یک منطقه را نشان می‌دهد: ۱/۸۰۰۰ درجه در ۱/۸۰۰۰ درجه (حدود ۱۴ متر × ۱۴ متر در خط استوا) یا کوچک‌تر. می‌توانید از «کدهای پلاس» به‌عنوان جایگزین نشانی خیابان در مکان‌هایی که نشانی خیابان وجود ندارد یا ساختمان‌ها شماره‌گذاری نشده‌اند یا خیابان‌ها نام‌گذاری نشده‌اند استفاده کنید.
Plus Code باید به‌صورت کد جهانی یا کد ترکیبی قالب‌بندی شود:
- کد جهانی از کد منطقه ۴ نویسه‌ای و کد محلی ۶ نویسه‌ای یا طولانی‌تر تشکیل شده است.
برای مثال، برای نشانی «1600 Amphitheatre Parkway, Mountain View, CA»، کد جهانی «849V» و کد محلی «CWC8+R9» است. سپس از کل «کد پلاس» ۱۰ کاراکتری برای مشخص کردن مقدار مکان به‌عنوان «849VCWC8+R9» استفاده می‌کنید.
- کد مرکب از یک کد محلی ۶ نویسه‌ای یا طولانی‌تر که با یک مکان صریح ترکیب شده است تشکیل می‌شود.
برای مثال، نشانی «450 Serra Mall, Stanford, CA 94305, USA» کد محلی «CRHJ+C3» دارد. برای نشانی ترکیبی، کد محلی را با شهر، ایالت، کد پستی، و بخش کشور نشانی در قالب «CRHJ+C3 Stanford, CA 94305, USA» ترکیب کنید.
برای مثال، با مشخص کردن نقطه بین راه برای مسیر
originوdestinationبااستفاده از «کدهای پلاس»، مسیری را محاسبه کنید:{ "origin":{ "address": "849VCWC8+R9" }, "destination":{ "address": "CRHJ+C3 Stanford, CA 94305, USA" }, "travelMode": "DRIVE" }
«کدهای پلاس» در «میاناهای برنامه‌سازی کاربردی پلاتفرم Google Maps» ازجمله تکمیل خودکار (جدید)، جزئیات مکان (جدید)، و میانای برنامه‌سازی کاربردی زمین‌کدیابی پشتیبانی می‌شود. برای مثال، می‌توانید از Geocoding API برای معکوس کردن مختصات عرض/طول جغرافیایی مکان مشخص‌شده استفاده کنید تا «کد پستی» مکان را تعیین کنید.