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

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

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

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

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

  • מידע רעיוני על קווים פוליגוניים

  • 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"
      }
    }
  ]
}

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

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

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

    הנקודות מציינות כערכים של קו רוחב וקו אורך, והם מיוצגים בפורמט נקודה צפה (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'

הגדרת איכות של קו פוליגוני

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

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