تعرض كل من طريقة computeRoutes (REST) وطريقة ComputeRoutes (gRPC) المسار الذي يمثّله شكل متعدّد الخطوط كجزء من الاستجابة. تعرض واجهات برمجة التطبيقات هذه نوعَين من الخطوط المتعدّدة:
الخطوط المتعدّدة الأساسية (تلقائي): تمثّل مسارًا ولكن بدون معلومات عن حركة المرور مضمّنة في الخطوط المتعدّدة. يتم تحصيل رسوم الطلبات التي تعرض خطوطًا متعدّدة أساسية وفقًا لسعر Routes Basic. مزيد من المعلومات حول الفوترة في 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 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
استخدام الخطوط المتعدّدة المرمّزة مع ميزة "البحث على طول المسار"
استخدِم البحث النصي (New) في Places API (New) للبحث على طول مسار محسوب. يمكنك تمرير الخطوط المتعدّدة المرمّزة لمسار محسوب مسبقًا من 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();