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

מפתחים באזור הכלכלי האירופי (EEA)

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

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

    ב-method‏ computeRoutes (REST) וב-ComputeRoutes, אפשר לשלוט בזה באמצעות polylineEncoding.

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

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

    ב-method‏ 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

מומלץ להציג במפה קווים פוליגוניים עם מידע על מצב התנועה באמצעות התכונות השונות שמוצעות בערכות ה-SDK של מפות Google, כולל צבעים, קווים ודפוסים בהתאמה אישית לאורך הקווים הפוליגוניים. למידע נוסף על השימוש בקווים פוליגוניים, קראו את המאמרים תכונות של קווים פוליגוניים ב-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 (חדש) כדי לחפש לאורך מסלול מחושב. מעבירים את הקו הפוליגוני המקודד של מסלול שחושב מראש מ-Compute Routes ב-Routes API לבקשה של חיפוש טקסט (חדש). התשובה תכיל מקומות שתואמים לקריטריונים לחיפוש ונמצאים גם בקרבת המסלול שצוין. לפרטים נוספים, ראו חיפוש לאורך מסלול.

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

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();