تُعرِض كلّ من الطريقة computeRoutes (REST) وطريقة ComputeRoutes (gRPC) المسار الذي يمثّله خطّ متعدد الأضلاع كجزء من الاستجابة. تعرض واجهات برمجة التطبيقات هذه نوعَين من الخطوط المتعددة:
الخطوط المتعددة الأساسية (التلقائية): تمثّل مسارًا بدون معلومات المرور المضمّنة في الخطوط المتعددة. يتمّ تحصيل رسوم من الطلبات التي تعرض خطوطًا متعددة أساسية باستخدام تعرفة "الخطوط الأساسية". مزيد من المعلومات حول الفوترة لواجهة برمجة التطبيقات Routes API
الخطوط المتعددة المراعيَة لحركة المرور، التي تحتوي على معلومات عن أحوال حركة المرور على طول المسار يتم التعبير عن أحوال حركة المرور من حيث فئات السرعة (
NORMALوSLOWوTRAFFIC_JAM) السارية على فاصل زمني معيّن من الخط المتعدّد. يتم تحصيل رسوم طلبات الخطوط المتعددة المراعية للزحام وفقًا لسعر Routes Preferred. مزيد من المعلومات عن الفوترة لواجهة برمجة التطبيقات Routes API للاطّلاع على التفاصيل، يُرجى الاطّلاع على مقالة ضبط جودة الخطوط المتعددة.
لمزيد من المعلومات عن الخطوط المتعددة، يُرجى الاطّلاع على:
تتيح لك أداة ترميز المضلّعات التفاعلية إنشاء مضلّعات مُشفَّرة في واجهة مستخدم أو فك ترميز المضلّعات لعرضها على خريطة. على سبيل المثال، استخدِم هذه الأداة لفك ترميز خط متعدد الأضلاع تم إنشاؤه باستخدام الرمز البرمجي أدناه.
طلب خط متعدّد الأضلاع أساسي لمسار أو رحلة أو خطوة
يتم تمثيل الشكل المتعدّد الخطوط بكائن 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.
على سبيل المثال، في نص الطلب:
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'
ضبط جودة Polyline
تحدِّد 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 الزيارات بين نقطتَي ملف polyline
2 و4:
{ "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 وفئة السرعة المقابلة.
يُرجى العِلم أنّ عدم توفّر فهرس البداية ضمن الفاصل الزمني يتوافق مع الفهرس 0
وفقًا ل
ممارسات proto3.
لا تكون قيمتَي startPolylinePointIndex وendPolylinePointIndex متعاقبتَين
دائمًا. على سبيل المثال:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
في هذه الحالة، كانت ظروف الزيارات متطابقة من الفهرس 2 إلى الفهرس 4.
عرض خطوط متعددة تراعي حركة المرور باستخدام حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google"
ننصحك بعرض الخطوط المتعددة المراعية للزحام على الخريطة باستخدام ميزات المتعدّدة التي تقدّمها حِزم تطوير البرامج (SDK) لخدمة "خرائط Google"، بما في ذلك الألوان المخصّصة والخطوط والرسومات المخصّصة على طول خطوط الالتفاف. لمزيد من التفاصيل حول استخدام الخطوط المتعددة، اطّلِع على ميزات الخطوط المتعددة لنظام التشغيل Android وميزات الخطوط المتعددة لنظام التشغيل iOS.
مثال على عرض Polyline
يمكن لمستخدمي حزمة SDK لتطبيق "خرائط Google" تحديد منطق تخصيص ربط بين فئات السرعة ومخططات عرض الخطوط المتعددة. على سبيل المثال، يمكن أن يقرر أحد المستخدمين عرض السرعة "العادية" كخط أزرق سميك على الخارطة، في حين يمكن أن يتم عرض السرعة "البطيئة" كخط برتقالي سميك.
تضيف المقتطفات التالية خطًا متعدّد الأضلاع أزرقًا سميكًا مع أقسام هندسية من ملبورن إلى بيرث. لمزيد من المعلومات، اطّلِع على مقالتَي تخصيص المظاهر (لنظام التشغيل Android) وتخصيص شكل الخطوط المتعددة (لنظام التشغيل iOS).
Android
Java
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
Objective-C
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();