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

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

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

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

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

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

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

מציינים איזה קו פוליגוני צריך להחזיר באמצעות Reply: Field mask:

  • ברמת המסלול, מחזירים קו פוליגוני בתגובה על ידי הכללת 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 method (REST) ו- ComputeRoutes, בשליטת polylineEncoding.

  • מספר הנקודות שמהן מורכב הקו הפוליגוני

    ככל שיש יותר נקודות, כך הקו הפוליגוני חלק יותר (במיוחד ).

    לחשבון computeRoutes method (REST) ו- ComputeRoutes, בשליטת polylineQuality.

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

כדי לשלוט בסוג הקווים הפוליגוניים, משתמשים באפשרות הבקשה polylineEncoding. המאפיין polylineEncoding קובע אם הקו הפוליגוני יקודד כ- ENCODED_POLYLINE (ברירת המחדל), כלומר פורמט מקודד Polyline Algorithm בשימוש, או 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) התאמה אישית של הקו הפוליגוני (ב-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