השיטה computeRoutes (REST) וה-method ComputeRoutes (gRPC) מחזירות שתיהן את המסלול שמיוצג על ידי קו פוליגוני כחלק מהתגובה. ממשקי ה-API האלה מחזירים שני סוגים של קווים פוליגוניים:
קו פוליגוני בסיסי (ברירת מחדל) מייצג מסלול אך ללא פרטי תנועה מוטמעים בקו הפוליגוני. בקשות שמחזירות קו פוליגוני בסיסי מחויבות לפי התעריף של Routes Basic. למידע נוסף על החיוב ב-Routs API
קו פוליגוני מבוסס תנועה – מידע על מצב התנועה לאורך המסלול. תנאי התנועה נקבעים לפי קטגוריות מהירות (
NORMAL
,SLOW
,TRAFFIC_JAM
) שרלוונטיות למרווח זמן נתון בקו הפוליגוני. בקשות לקווים פוליגוניים שמודעים לתנועה מחויבות לפי התעריף המועדף של 'מסלולים'. למידע נוסף על החיוב ב-Routes API לפרטים נוספים קראו את המאמר הגדרת איכות של פוליגונים
למידע נוסף על קווים פוליגוניים, ראה:
באמצעות Interactive Polyline Encoder Tool אפשר ליצור קווים פוליגוניים מקודדים בממשק משתמש או לפענח קווים פוליגוניים להצגה במפה. לדוגמה, תוכלו להשתמש בכלי הזה כדי לפענח קו פוליגוני שנוצר על ידי הקוד שלמטה.
בקשת קו פוליגוני בסיסי למסלול, לקטע או לשלב
קו פוליגוני מיוצג על ידי אובייקט 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" } } ] }
איכות של קווים פוליגוניים
ניתן לתאר את האיכות של קו פוליגוני במונחים הבאים:
הדיוק של הנקודות הצפה (floating-point) של הנקודות
הנקודות מצוינים כערכים של קווי אורך ורוחב, מיוצגים בפורמט של נקודה צפה עם דיוק יחיד. השיטה הזאת מתאימה לערכים קטנים (שאפשר לייצג במדויק), אבל הדיוק יורד ככל שהערכים גדלים בגלל שגיאות בעיגול נקודה צפה (floating-point).
ב-method computeRoutes (REST) ו-ComputeRoutes, השליטה הזו נקבעת על ידי
polylineEncoding
.מספר הנקודות שמהן מורכב הקו הפוליגוני
ככל שיש יותר נקודות, כך הקו הפוליגוני חלק יותר (במיוחד בעקומות).
ב-method computeRoutes (REST) ו-ComputeRoutes, השליטה הזו נקבעת על ידי
polylineQuality
.
הגדרת סוג קידוד של קו פוליגוני
כדי לשלוט בסוג של הקו הפוליגוני, אפשר להשתמש באפשרות הבקשה polylineEncoding
.
המאפיין polylineEncoding
קובע אם הקו הפוליגוני יקודד
ENCODED_POLYLINE
(ברירת המחדל), כלומר
ייעשה שימוש בפורמט האלגוריתם המקודד של 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'
הגדרת איכות של Poyline
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.
עיבוד קווים פוליגוניים המודעים לתנועה באמצעות ה-SDK של מפות Google
אנחנו ממליצים להציג במפה קווים פוליגוניים מותאמים לתנועה באמצעות התכונות השונות שמוצעות על ידי ערכות ה-SDK של מפות Google, כולל צבעים מותאמים אישית, קווים ודפוסים בהתאמה אישית, לאורך הקווים הפוליגוניים. מידע נוסף על השימוש בקווים פוליגוניים זמין במאמרים תכונות של Polyline ל-Android ותכונות של Polyline ל-iOS.
דוגמה לעיבוד קווים פוליגוניים
למשתמשים ב-SDK של מפות Google יש הזדמנות להגדיר לוגיקת מיפוי מותאמת אישית בין קטגוריות המהירות לבין סכימות העיבוד הפוליגוניות. לדוגמה, אפשר להציג את המהירות NORMAL כקו כחול עבה במפה, ואת המהירות SLOW אפשר להציג כקו כתום עבה.
קטעי הקוד הבאים מוסיפים קו פוליגוני כחול ועבה עם קטעים גיאודזיים מלבורן עד פרת'. מידע נוסף זמין במאמר התאמה אישית של המראה (ל-Android) ובמאמר התאמה אישית של ה-Polyline (ב-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