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

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

  • קו מרובה בסיסי (ברירת המחדל), מייצג מסלול אבל בלי מידע על תנועה שמוטמע בקו המרובה. בקשות שמחזירות קו פוליגוני בסיסי יחויבו לפי התעריף של 'מסלולים בסיסיים'. מידע נוסף על חיוב ב-Routes API

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

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

  • מידע רעיוני ב-Polylines

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

בקשה לקו פוליגוני בסיסי של מסלול, רגל או שלב

קו פוליגוני מיוצג על ידי אובייקט 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"
      }
    }
  ]
}

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

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

  • רמת הדיוק של הנקודות הצפה

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

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

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

מומלץ להציג במפה קווים פוליגונים עם מידע על מצב התנועה באמצעות התכונות השונות שזמינות ב-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