ה-method computeRoutes (REST) ו- ComputeRoutes method (gRPC) מחזירה את הנתיב שמיוצג על ידי קו פוליגוני כחלק תשובה. ממשקי ה-API האלה מחזירים שני סוגים של קווים פוליגוניים:
קו פוליגוני בסיסי (ברירת מחדל), מייצג מסלול אבל ללא תנועה שמוטבע בקו הפוליגוני. בקשות שמחזירות קו פוליגוני בסיסי מחויבים לפי התעריף של 'מסלולים בסיסיים'. מידע נוסף על חיוב ל-Routes API.
קו פוליגוני שמותאם לתנועה, מכיל מידע על מצב התנועה לאורך המסלול. מצב התנועה מבוטאת מבחינת המהירות. קטגוריות (
NORMAL
,SLOW
,TRAFFIC_JAM
) שרלוונטיות למרווח נתון של הקו הפוליגוני. בקשות לקווים פוליגוניים שמתחשבים בתנועה מחויבות ב תעריף מועדף למסלולים. יש לך אפשרות לקרוא מידע נוסף על חיוב עבור Routes API. פרטים נוספים זמינים במאמר הגדרת איכות של קו פוליגוני
למידע נוסף על קווים פוליגוניים, ראו:
כלי מקודד אינטראקטיבי למקודד קונפוטיבי מאפשרת ליצור קווים פוליגוניים מקודדים בממשק משתמש או לפענח קווים פוליגוניים שיוצגו מפה. לדוגמה, השתמש בכלי זה כדי לפענח קו פוליגוני שנוצר על ידי שבהמשך.
בקשה לקו פוליגוני בסיסי של מסלול, רגל או שלב
קו פוליגוני מיוצג על ידי אובייקט Polyline (ב-REST) או Polyline (ב-gRPC). אפשר להחזיר קו פוליגוני בתגובה ברמת המסלול, השלב והשלב.
מציינים איזה קו פוליגוני צריך להחזיר באמצעות Reply: Field mask:
ברמת המסלול, מחזירים קו פוליגוני בתגובה על ידי הכללת
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) עם דיוק יחיד. שיטה זו מתאימה לערכים קטנים (שאפשר לייצג בצורה מדויקת), אבל הדיוק פוחת כערכים בגלל שגיאות בעיגול הנקודה הצפה.
לחשבון computeRoutes method (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