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

מפתחים באזור הכלכלי האירופי (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"
      }
    }
  ]
}

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

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

  • הדיוק של הנקודות בשיטת הנקודה הצפה

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

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

מומלץ להציג במפה קווים פוליגוניים עם נתוני תנועה באמצעות התכונות השונות שמוצעות ב-Google Maps SDKs, כולל צביעה, קווים ודוגמאות בהתאמה אישית לאורך הקווים הפוליגוניים. לפרטים נוספים על השימוש בקווי פוליגון, אפשר לעיין במאמרים תכונות של קווי פוליגון ל-Android ותכונות של קווי פוליגון ל-iOS.

דוגמה לעיבוד של קו פוליגון

משתמשי Maps SDK יכולים להגדיר לוגיקת מיפוי מותאמת אישית בין קטגוריות המהירות לבין סכימות העיבוד של קווי ה-polyline. לדוגמה, אפשר להחליט להציג מהירות 'רגילה' כקו כחול עבה במפה, ומהירות 'איטית' כקו כתום עבה.

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

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

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