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

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

  • קו פוליגוני בסיסי (ברירת מחדל) מייצג מסלול אבל בלי מידע על התנועה שמוטמע בקו הפוליגוני. בקשות שמחזירות קו פוליגוני בסיסי יחויבו לפי התעריף של 'מסלולים בסיסיים'. למידע נוסף על החיוב ב-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"
      }
    }
  ]
}

איכות קו פוליגוני

אפשר לתאר את האיכות של קו פוליגוני במונחים הבאים:

  • רמת הדיוק של הנקודות בנקודה צפה (floating-point)

    הנקודות מציינות כערכים של קו רוחב וקו אורך, והם מיוצגים בפורמט נקודה צפה (floating-point) ברמת דיוק יחיד. השיטה הזו מתאימה לערכים קטנים (שאפשר לייצג בצורה מדויקת), אבל הדיוק יורד ככל שהערכים עולים בגלל שגיאות בעיגול הנקודה הצפה.

    ב-method 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.

עיבוד פוליגונים שמותאמים לתנועה באמצעות SDK של מפות Google

מומלץ להציג במפה קווים פוליגוניים שמתחשבים בתנועה באמצעות התכונות השונות שמוצעות על ידי ערכות ה-SDK של מפות Google, כולל צביעה, קווים ודפוסים מותאמים אישית לאורך הקווים הפוליגוניים. לפרטים נוספים על השימוש בקווים פוליגוניים, ראו תכונות של Polyline ל-Android ותכונות של Polyline ל-iOS.

דוגמה לעיבוד של קו מרובה

משתמשי Maps SDK יכולים להגדיר לוגיקה מותאמת אישית של מיפוי בין קטגוריות המהירות לבין סכימות הרינדור של קווים פוליגונליים. לדוגמה, ייתכן שנחליט להציג את המהירות '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