דף זה תורגם על ידי Cloud Translation API.

בקשת נתיבים מרובים

השיטה computeRoutes (REST) וה-method ComputeRoutes (gRPC) מחזירות שתיהן את המסלול שמיוצג על ידי קו פוליגוני כחלק מהתגובה. ממשקי ה-API האלה מחזירים שני סוגים של קווים פוליגוניים:

קו פוליגוני בסיסי (ברירת מחדל) מייצג מסלול אך ללא פרטי תנועה מוטמעים בקו הפוליגוני. בקשות שמחזירות קו פוליגוני בסיסי מחויבות לפי התעריף של Routes Basic. למידע נוסף על החיוב ב-Routs API
קו פוליגוני מבוסס תנועה – מידע על מצב התנועה לאורך המסלול. תנאי התנועה נקבעים לפי קטגוריות מהירות (NORMAL, SLOW, TRAFFIC_JAM) שרלוונטיות למרווח זמן נתון בקו הפוליגוני. בקשות לקווים פוליגוניים שמודעים לתנועה מחויבות לפי התעריף המועדף של 'מסלולים'. למידע נוסף על החיוב ב-Routes API לפרטים נוספים קראו את המאמר הגדרת איכות של פוליגונים

למידע נוסף על קווים פוליגוניים, ראה:

מידע רעיוני על קווים פוליגוניים
באמצעות Interactive Polyline Encoder Tool אפשר ליצור קווים פוליגוניים מקודדים בממשק משתמש או לפענח קווים פוליגוניים להצגה במפה. לדוגמה, תוכלו להשתמש בכלי הזה כדי לפענח קו פוליגוני שנוצר על ידי הקוד שלמטה.

הערה: תווים מיוחדים בפוליגונים שהוחזרו על ידי ה-API ל-REST הם מסוג JSON. כדי להציג את הקווים הפוליגוניים האלה בכלי העזר האינטראקטיבי של מקודד Polyline, צריך קודם לבטל אותם. יש הרבה כלים לביצוע בריחה ל-JSON, כמו Freeformatter.

בקשת קו פוליגוני בסיסי למסלול, לקטע או לשלב

קו פוליגוני מיוצג על ידי אובייקט Polyline (REST) או Polyline (gRPC). אפשר להחזיר קו פוליגוני בתגובה ברמת המסלול, הרגל והשלב.

השתמשו באנונימיזציה של שדה התגובה כדי לציין איזה קו פוליגוני להחזיר:

ברמת המסלול, מחזירים קו פוליגוני בתגובה על ידי הוספת routes.polyline במסכה של שדה התשובה.
ברמת הרגל, מחזירים את הערך routes.legs.polyline בתגובה לקו פוליגוני בתגובה לכל קטע במסלול.

הערה: כל רגל תואמת לנסיעה בין שתי ציוני דרך כאשר via שגוי לגבי ציון הדרך שמציין עצירה במסלול. לדוגמה, למסלול ללא נקודות ביניים יש רק רגל אחת. למסלול שכולל ציוני דרך אמצעיים עם עצירה יש שתי רגליים. מסלול שכולל נקודת דרך אחת בינונית שבה via מוגדר כ-true, כולל רגל אחת.
ברמת השלב, מחזירים קו פוליגוני בתגובה לכל שלב ברגל, על ידי הוספת 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