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