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

גם ה-method‏ computeRoutes (‏REST) וגם ה-method‏ 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.

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

שימוש בקוים פוליגונים מוצפנים עם התכונה 'חיפוש לאורך המסלול'

שימוש בחיפוש טקסט של Places API כדי לחפש לאורך מסלול מחושב. מעבירים את קו הפוליגון המקודד של מסלול שחושב מראש מ-Routes API Compute Routes לבקשת החיפוש בטקסט. התשובה תכלול מקומות שתואמים לקריטריונים של החיפוש וגם נמצאים ליד המסלול שצוין. פרטים נוספים זמינים במאמר חיפוש לאורך מסלול.

לדוגמה, כדי להציג בתי קפה לאורך המסלול בין נקודת היציאה ליעד:

Node.js

const API_KEY = 'YOUR_API_KEY';
const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes';
const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';



function init(){
    const routes_request = {
        "origin":{
            "address": "1600 Amphitheatre Parkway, Mountain View, CA"
        },
        "destination":{
            "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
        },
        "travelMode": "DRIVE"
    };
    const textSearch_request = {
        "textQuery": "cafe",
        "searchAlongRouteParameters": {
            "polyline": {
                "encodedPolyline": ""
            }
        }
    };
    fetchResources(routes_service,routes_request).then(routes => {
        textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline;
        fetchResources(textSearch_service,textSearch_request).then(places => {
            console.log(places);
        });
    });
}
async function fetchResources(resource,reqBody){
    const response = await fetch(resource, {
        method: 'POST',
        body: JSON.stringify(reqBody),
        headers: {
            'Content-Type': 'application/json',
            'X-Goog-Api-Key': API_KEY,
            'X-Goog-FieldMask': '*'
        }
    });
    const responseJSON = await response.json();
    return responseJSON;
}
init();