روش computeRoutes (REST) و روش ComputeRoutes (gRPC) هر دو مسیر را به‌صورت چندخطی به‌عنوان بخشی از پاسخ برمی‌گردانند. این میاناهای برنامه‌سازی کاربردی دو نوع چندخطی برمی‌گردانند:
چندخطی پایه (پیش‌فرض)، نمایانگر مسیر است اما اطلاعات ترافیک در چندخطی جاسازی نشده است. درخواست‌هایی که چندخطی پایه برمی‌گردانند با نرخ «مسیرهای پایه» صورت‌حساب می‌شوند. درباره صدور صورت‌حساب برای Routes API بیشتر بدانید.
چندخطی آگاه از ترافیک، حاوی اطلاعاتی درباره شرایط ترافیک درطول مسیر است. شرایط ترافیک براساس دسته‌های سرعت (
NORMAL،SLOW،TRAFFIC_JAM) که در بازه مشخصی از چندخطی اعمال می‌شود بیان می‌شود. درخواست‌های چندخطی‌های آگاه از ترافیک با نرخ Routes Preferred صورت‌حساب می‌شود. درباره صدور صورت‌حساب برای Routes API بیشتر بدانید. برای جزئیات، به پیکربندی کیفیت چندخطی مراجعه کنید
برای اطلاعات بیشتر درباره چندخطی‌ها، به این مقاله مراجعه کنید:
Interactive Polyline Encoder Utility به شما امکان می‌دهد چندخطی‌های کدگذاری‌شده را در میانای کاربر ایجاد کنید یا چندخطی‌ها را برای نمایش روی نقشه رمزگشایی کنید. برای مثال، از این ابزار برای رمزگشایی چندخطی ایجادشده توسط کد زیر استفاده کنید.
درخواست چندخطی پایه برای مسیر، بخش، یا مرحله
چندخطی با شیء Polyline (REST) یا Polyline (gRPC) نشان داده می‌شود. می‌توانید یک چندخطی را در پاسخ در سطح مسیر، بخش، و مرحله برگردانید.
بااستفاده از ماسک فیلد پاسخ، مشخص کنید کدام چندخطی برگردانده شود:
در سطح مسیر، با گنجاندن
routes.polylineدر ماسک فیلد پاسخ، چندخطی را در پاسخ برگردانید.در سطح مسیر، با گنجاندن
routes.legs.polyline، یک چندخطی در پاسخ برای هر مسیر از مسیر برگردانید.در سطح مرحله، با گنجاندن
routes.legs.steps.polyline، چندخطی را در پاسخ برای هر مرحله از بخش برگردانید.
برای مثال، برای برگرداندن چندخطی برای کل مسیر، برای هر بخش، و برای هر مرحله از هر بخش:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
این درخواست پاسخ زیر را برمی‌گرداند که شامل چندخطی برای مسیر، برای هر بخش از مسیر، و برای هر مرحله از بخش است:
{ "routes": [ { "legs": [ { "polyline": { "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?" } }, "steps": [ { "polyline": { "encodedPolyline": "kclcF...@sC@YIOKI" } }, { "polyline": { "encodedPolyline": "wblcF~...SZSF_@?" } }, ... ], "distanceMeters": 56901, "duration": "2420s", "polyline": { "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?" } } ] }
چون این درخواست فقط حاوی مبدأ و مقصد است، مسیر برگردانده‌شده فقط حاوی یک بخش است. بنابراین، چندخطی برای بخش و برای مسیر یکسان است.
اگر نقطه‌مسیر میانی به درخواست اضافه کنید، مسیر برگردانده‌شده شامل دو بخش است:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "intermediates": [ { "address": "450 Serra Mall, Stanford, CA 94305, USA"}, ], "travelMode": "DRIVE", }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
این درخواست دو بخش را برمی‌گرداند که هرکدام چندخطی منحصربه‌فردی دارند، و یک چندخطی برای کل مسیر:
{ "routes": [ { "legs": [ { "polyline": { "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG" } "steps": [ { "polyline": { "encodedPolyline": "kclcFfqch...YIOKI" } }, ... }, { "polyline": { "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G" } "steps": [ { "polyline": { "encodedPolyline": "uypeFbo`jVgJq...PoBiC" } }, ... } ], "distanceMeters": 68403, "duration": "3759s", "polyline": { "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE" } } ] }
کیفیت چندخطی
کیفیت چندخطی را می‌توان با اصطلاحات زیر توصیف کرد:
دقت ممیز شناور نقاط
نقاط به‌صورت مقادیر طول و عرض جغرافیایی مشخص می‌شوند که در قالب ممیز شناور با دقت تکی نشان داده می‌شوند. این روش برای مقادیر کوچک (که می‌توانند به‌طور دقیق نمایش داده شوند) به‌خوبی کار می‌کند، اما با افزایش مقادیر، دقت به‌دلیل خطاهای گرد کردن ممیز شناور کاهش می‌یابد.
در روش computeRoutes (REST) و ComputeRoutes، این مورد توسط
polylineEncodingکنترل می‌شود.تعداد نقطه‌هایی که چندخطی را تشکیل می‌دهند
هرچه تعداد نقاط بیشتر باشد، چندخطی هموارتر است (به‌ویژه در منحنی‌ها).
در روش computeRoutes (REST) و ComputeRoutes، این مورد توسط
polylineQualityکنترل می‌شود.
پیکربندی نوع کدبندی چندخطی
از گزینه درخواست polylineEncoding برای کنترل نوع چندخطی استفاده کنید. ویژگی
polylineEncoding کنترل می‌کند که چندخطی به‌صورت
ENCODED_POLYLINE (پیش‌فرض) کدگذاری شود، یعنی از قالب الگوریتم چندخطی
کدگذاری‌شده استفاده شود، یا
GEO_JSON_LINESTRING، یعنی از قالب GeoJSON LineString استفاده شود.
برای مثال، در متن درخواست:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE", "polylineEncoding": "ENCODED_POLYLINE" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
پیکربندی کیفیت چندخطی
polylineQuality کیفیت چندخطی را به‌صورت HIGH_QUALITY یا
OVERVIEW (پیش‌فرض) مشخص می‌کند. با OVERVIEW، چندخطی بااستفاده از تعداد کمی نقطه تشکیل می‌شود و تأخیر درخواست کمتری نسبت‌به HIGH_QUALITY دارد.
برای مثال، در متن درخواست:
{ "origin":{ "location":{ "latLng":{ "latitude": 37.419734, "longitude": -122.0827784 } } }, "destination":{ "location":{ "latLng":{ "latitude": 37.417670, "longitude": -122.079595 } } }, "travelMode": "DRIVE", "routingPreference": "TRAFFIC_AWARE", "polylineQuality": "HIGH_QUALITY", "polylineEncoding": "ENCODED_POLYLINE", "departureTime": "2023-10-15T15:01:23.045123456Z", ... }
درخواست چندخطی با آگاهی از ترافیک
نمونه‌های نشان‌داده‌شده در بالا همگی چندخطی‌های پایه را برمی‌گردانند، یعنی چندخطی‌های بدون اطلاعات ترافیک. علاوه‌براین، می‌توانید درخواست کنید که چندخطی حاوی اطلاعات ترافیک برای مسیر و برای هر بخش از مسیر باشد.
چندخطی‌های آگاه از ترافیک حاوی اطلاعاتی درباره وضعیت ترافیک درطول مسیر هستند. شرایط ترافیک برحسب دسته‌های سرعت
(NORMAL، SLOW، TRAFFIC_JAM) برای فاصله زمانی مشخصی از چندخطی پاسخ بیان می‌شود.
فاصله‌ها با نمایه‌های نقاط چندخطی شروع (شامل) و
پایان (غیرشامل) تعریف می‌شوند.
برای مثال، پاسخ زیر ترافیک NORMAL را بین نقاط چندخطی ۲ و ۴ نشان می‌دهد:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
برای درخواست محاسبه چندخطی آگاه از ترافیک، ویژگی‌های زیر را در درخواست تنظیم کنید:
برای فعال کردن محاسبه ترافیک، فیلد آرایه
extraComputationsرا رویTRAFFIC_ON_POLYLINEتنظیم کنید.travelModeرا رویDRIVEیاTWO_WHEELERتنظیم کنید. درخواست برای هر حالت سفر دیگری خطا برمی‌گرداند.اولویت مسیریابی
TRAFFIC_AWAREیاTRAFFIC_AWARE_OPTIMALرا در درخواست مشخص کنید. برای اطلاعات بیشتر، پیکربندی کیفیت درمقابل تأخیر را ببینید.پوشش فیلد پاسخ را تنظیم کنید که مشخص می‌کند ویژگی‌های پاسخ برگردانده شود:
در سطح مسیر، همه اطلاعات سفر را در پاسخ با گنجاندن
routes.travelAdvisoryدر ماسک فیلد پاسخ برگردانید. برای برگرداندن فقط اطلاعات ترافیک،routes.travelAdvisory.speedReadingIntervalsرا مشخص کنیددر سطح بخش، همه اطلاعات سفر را در پاسخ برای هر بخش از مسیر با گنجاندن
routes.legs.travelAdvisoryبرگردانید. برای برگرداندن فقط اطلاعات ترافیک،routes.legs.travelAdvisory.speedReadingIntervalsرا مشخص کنید.
curl -X POST -d '{
"origin":{
"address": "1600 Amphitheatre Parkway, Mountain View, CA"
},
"destination":{
"address": "24 Willie Mays Plaza, San Francisco, CA 94107"
},
"travelMode": "DRIVE",
"extraComputations": ["TRAFFIC_ON_POLYLINE"],
"routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \
'https://routes.googleapis.com/directions/v2:computeRoutes'نمونه پاسخ برای چندخطی بااطلاع از ترافیک
در پاسخ، داده‌های ترافیک در چندخطی کدگذاری می‌شود و در فیلد travelAdvisory از نوع شیء RouteLegTravelAdvisory (هر بخش) و شیء RouteTravelAdvisory (مسیر) قرار می‌گیرد.
برای مثال:
{
"routes": [
{
"legs": {
"polyline": {
"encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
},
// Traffic data for the leg.
"travelAdvisory": {
"speedReadingIntervals": [
{
"endPolylinePointIndex": 1,
"speed": "NORMAL"
},
{
"startPolylinePointIndex": 1,
"endPolylinePointIndex": 2,
"speed": "SLOW"
},
{
"startPolylinePointIndex": 2,
"endPolylinePointIndex": 4,
"speed": "NORMAL"
}
]
}
},
"polyline": {
"encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
},
// Traffic data for the route.
"travelAdvisory": {
"speedReadingIntervals": [
{
"endPolylinePointIndex": 1,
"speed": "NORMAL"
},
{
"startPolylinePointIndex": 1,
"endPolylinePointIndex": 2,
"speed": "SLOW"
},
{
"startPolylinePointIndex": 2,
"endPolylinePointIndex": 4,
"speed": "NORMAL"
}
]
}
}
]
}
RouteTravelAdvisory و RouteLegTravelAdvisory هر دو شامل فیلد آرایه‌ای
به‌نام speedReadingIntervals هستند که حاوی اطلاعات سرعت ترافیک است. هر
شیء در آرایه با یک شیء
SpeedReadingInterval (REST) یا
SpeedReadingInterval
(gRPC) نشان داده می‌شود.
شیء SpeedReadingInterval شامل خواندن سرعت برای فاصله زمانی مسیر است،
مانند NORMAL، SLOW، یا TRAFFIC_JAM. آرایه کامل اشیاء کل چندخطی مسیر را بدون هم‌پوشانی پوشش می‌دهد. نقطه شروع یک بازه مشخص‌شده با نقطه پایان بازه قبلی یکسان است.
هر بازه با startPolylinePointIndex،
endPolylinePointIndex، و دسته سرعت مربوطه توصیف می‌شود. توجه داشته باشید که
نبود نمایه شروع در فاصله زمانی با نمایه ۰ مطابق با
شیوه‌های
proto3 مطابقت دارد.
مقادیر startPolylinePointIndex و endPolylinePointIndex همیشه متوالی نیستند. برای مثال:
{
"startPolylinePointIndex": 2,
"endPolylinePointIndex": 4,
"speed": "NORMAL"
}
در این مورد، وضعیت ترافیک از نمایه ۲ تا نمایه ۴ یکسان بود.
ارائه چندخطی‌های آگاه از ترافیک با Maps SDK
توصیه می‌کنیم چندخطی‌های آگاه از ترافیک را بااستفاده از ویژگی‌های مختلف ارائه‌شده توسط کیت‌های توسعه نرم‌افزار Google Maps، ازجمله رنگ‌آمیزی سفارشی، خطوط، و الگوها درطول چندخطی، روی نقشه نمایش دهید. برای جزئیات بیشتر درباره استفاده از چندخطی‌ها، ویژگی‌های چندخطی برای Android و ویژگی‌های چندخطی برای iOS را ببینید.
نمونه پردازش چندخطی
کاربران Maps SDK این فرصت را دارند که منطق نگاشت سفارشی‌شده‌ای را بین دسته‌های سرعت و طرح‌های رندر چندخطی تعریف کنند. به‌عنوان مثال، ممکن است تصمیم گرفته شود که سرعت «عادی» به‌صورت خط آبی ضخیم روی نقشه نمایش داده شود، درحالی‌که سرعت «آهسته» ممکن است به‌صورت خط نارنجی ضخیم نمایش داده شود.
قطعه کدهای زیر یک چندخطی آبی ضخیم با بخش‌های ژئودزیک از ملبورن به پرت اضافه می‌کنند. برای اطلاعات بیشتر، سفارشی‌سازی ظاهر (برای Android) و سفارشی‌سازی چندخطی (برای iOS) را ببینید.
Android
جاوا
Polyline line = map.addPolyline(new PolylineOptions() .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734)) .width(25) .color(Color.BLUE) .geodesic(true));
Kotlin
val line: Polyline = map.addPolyline( PolylineOptions() .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734)) .width(25f) .color(Color.BLUE) .geodesic(true) )
iOS
آبجکتیو-سی
GMSMutablePath *path = [GMSMutablePath path]; [path addLatitude:-37.81319 longitude:144.96298]; [path addLatitude:-31.95285 longitude:115.85734]; GMSPolyline *polyline = [GMSPolyline polylineWithPath:path]; polyline.strokeWidth = 10.f; polyline.strokeColor = .blue; polyline.geodesic = YES; polyline.map = mapView;
Swift
let path = GMSMutablePath() path.addLatitude(-37.81319, longitude: 144.96298) path.addLatitude(-31.95285, longitude: 115.85734) let polyline = GMSPolyline(path: path) polyline.strokeWidth = 10.0 polyline.geodesic = true polyline.map = mapView
استفاده از چندخطی‌های کدبندی‌شده با «جستجو در طول مسیر»
از «جستجوی نوشتار (جدید)» در Places API (جدید) برای جستجو درطول مسیر محاسبه‌شده استفاده کنید. چندخطی کدبندی‌شده مسیر ازپیش محاسبه‌شده را از «محاسبه مسیرهای Routes API» به درخواست «جستجوی نوشتار (جدید)» ارسال می‌کنید. سپس پاسخ حاوی مکان‌هایی است که با معیارهای جستجو مطابقت دارند و همچنین در نزدیکی مسیر مشخص‌شده قرار دارند. برای جزئیات، به جستجو درطول مسیر مراجعه کنید.
برای مثال، برای برگرداندن کافه‌های موجود در مسیر بین مبدأ و مقصد:
Node.js
const API_KEY = 'YOUR_API_KEY'; const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes'; const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';function init(){ const routes_request = { "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }; const textSearch_request = { "textQuery": "cafe", "searchAlongRouteParameters": { "polyline": { "encodedPolyline": "" } } }; fetchResources(routes_service,routes_request).then(routes => { textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline; fetchResources(textSearch_service,textSearch_request).then(places => { console.log(places); }); }); } async function fetchResources(resource,reqBody){ const response = await fetch(resource, { method: 'POST', body: JSON.stringify(reqBody), headers: { 'Content-Type': 'application/json', 'X-Goog-Api-Key': API_KEY, 'X-Goog-FieldMask': '*' } }); const responseJSON = await response.json(); return responseJSON; } init();