ה-method computeRoutes (REST) ו- ComputeRoutes method (gRPC) מחזירה את הנתיב שמיוצג על ידי קו פוליגוני כחלק תשובה. ממשקי ה-API האלה מחזירים שני סוגים של קווים פוליגונליים:
קו מרובה בסיסי (ברירת המחדל), מייצג מסלול אבל בלי מידע על תנועה שמוטמע בקו המרובה. בקשות שמחזירות קו פוליגוני בסיסי מחויבים לפי התעריף של 'מסלולים בסיסיים'. מידע נוסף על חיוב ב-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 method (REST) ו- ComputeRoutes, בשליטת
polylineQuality.
הגדרת סוג הקידוד של קו פוליגוני
כדי לשלוט בסוג הקווים הפוליגוניים, משתמשים באפשרות הבקשה polylineEncoding.
המאפיין polylineEncoding קובע אם הקו הפוליגוני יקודד כ-
ENCODED_POLYLINE (ברירת המחדל), כלומר
פורמט מקודד Polyline Algorithm
בשימוש, או 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את החישוב של תנועת הגולשים.מגדירים את הערך
DRIVEאו הערךTWO_WHEELERבמאפייןtravelMode. בקשות לכל סוג אחר מצב נסיעה מחזיר שגיאה.צריך לציין את הניתוב
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
מומלץ להציג במפה קווים פוליגונים עם מידע על מצב התנועה באמצעות התכונות השונות שזמינות ב-Google Maps SDK, כולל צביעה בהתאמה אישית, קווים ודפוסים לאורך קטעי הקו הפוליגוני. לפרטים נוספים על השימוש בקווים פוליגוניים, לראות תכונות Polyline ל-Android ותכונות של Polyline ל-iOS.
דוגמה לעיבוד של קו פוליגוני
למשתמשים ב-SDK של מפות Google יש הזדמנות להגדיר מיפוי מותאם אישית הלוגיקה בין קטגוריות המהירות לסכימות העיבוד של קווים פוליגוניים. בתור לדוגמה, אפשר להציג את הערך 'NORMAL'. מהירות גבוהה כמו קו כחול עבה על מפה בזמן "SLOW" ייתכן שהמהירות תוצג כקו כתום עבה, לדוגמה.
קטעי הקוד הבאים מוסיפים קו פוליגוני כחול ועבה עם פלחים גיאודזיים מתוך מלבורן לפרת'. מידע נוסף זמין במאמרים התאמה אישית של המראה (ל-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