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

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

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

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

    בשיטה 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

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

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

משתמשי Maps SDK יכולים להגדיר לוגיקה מותאמת אישית של מיפוי בין קטגוריות המהירות לבין הסכימות של עיבוד הפוליגונים. לדוגמה, אפשר להציג מהירות 'רגילה' כקו כחול עבה במפה, ומהירות 'איטית' כקו כתום עבה.

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