يعرض كلّ من الطريقتَين computeRoutes (REST) وComputeRoutes (gRPC) المسار الممثّل بخط متعدد الأضلاع كجزء من الردّ. تعرض واجهات برمجة التطبيقات هذه نوعَين من الخطوط المتعددة:
خطوط متعددة أساسية (تلقائية): تمثّل مسارًا ولكن بدون معلومات حول حركة المرور مضمّنة في الخطوط المتعددة. يتم تحصيل رسوم من الطلبات التي تعرض خطًا متعدد الأضلاع أساسيًا وفقًا لسعر Routes Basic. مزيد من المعلومات حول الفوترة في Routes API
تحتوي الخطوط المتعددة المدرِكة لحركة المرور على معلومات حول أحوال حركة المرور على طول المسار. يتم التعبير عن أحوال حركة المرور من خلال فئات السرعة (
NORMALوSLOWوTRAFFIC_JAM) التي تنطبق على فترة زمنية معيّنة من الخط المتعدد الأضلاع. يتم تحصيل رسوم مقابل طلبات الخطوط المتعددة الأضلاع التي تراعي حركة المرور وفقًا لسعر "المسارات المفضّلة". مزيد من المعلومات عن الفوترة في 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 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 بين النقطتين 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.
عرض خطوط متعدّدة الأضلاع تراعي حركة المرور باستخدام "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google"
ننصحك بعرض خطوط متعددة الأضلاع تراعي حركة المرور على الخريطة باستخدام الميزات المختلفة التي توفّرها حِزم تطوير البرامج (SDK) الخاصة بـ "خرائط Google"، بما في ذلك الألوان المخصّصة والخطوط والأنماط على طول أجزاء الخط المتعدد الأضلاع. لمزيد من التفاصيل حول استخدام الخطوط المتعددة الأضلاع، راجِع ميزات الخطوط المتعددة الأضلاع في Android وميزات الخطوط المتعددة الأضلاع في iOS.
مثال على عرض خطوط متعددة
يمكن لمستخدمي حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" تحديد منطق مخصّص للربط بين فئات السرعة ومخططات عرض الخطوط المتعددة. على سبيل المثال، يمكن اختيار عرض السرعة "عادية" كخط أزرق سميك على الخريطة، بينما يتم عرض السرعة "بطيئة" كخط برتقالي سميك، مثلاً.
تضيف المقتطفات التالية خطًا متعدد الأضلاع أزرق سميكًا مع مقاطع جيوديسية من ملبورن إلى بيرث. لمزيد من المعلومات، يُرجى الاطّلاع على تخصيص المظاهر (لنظام التشغيل 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
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 Compute Routes إلى طلب البحث النصي (الجديد). يتضمّن الردّ بعد ذلك الأماكن التي تطابق معايير البحث وتقع أيضًا بالقرب من المسار المحدّد. لمعرفة التفاصيل، يُرجى الاطّلاع على البحث على طول طريق.
على سبيل المثال، لعرض المقاهي على طول المسار بين نقطة الانطلاق والوجهة:
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();