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

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

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

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

  • קו פוליגון עם נתונים על מצב התנועה, שמכיל מידע על מצב התנועה לאורך המסלול. מצב התנועה מוצג באמצעות קטגוריות של מהירות (NORMAL, SLOW, TRAFFIC_JAM) שרלוונטיות למרווח נתון של הקו הפוליגוני. החיוב על בקשות של קווי פוליגון עם נתוני תנועה הוא לפי התעריף של Routes Preferred. מידע נוסף על חיוב ב-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"
      }
    }
  ]
}

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

איכות הקו המקוטע יכולה להיות אחת מהאפשרויות הבאות:

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

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

    בשיטה 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 SDKs, כולל צביעה, קווים ודפוסים מותאמים אישית לאורך הקווים הפוליגוניים. לפרטים נוספים על השימוש בקווי פוליגון, אפשר לעיין במאמרים תכונות של קווי פוליגון ל-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 Text Search כדי לחפש לאורך מסלול מחושב. מעבירים את הקו הפוליגוני המקודד של מסלול שחושב מראש מ-Routes API Compute Routes לבקשת Text Search. התשובה תכיל מקומות שתואמים לקריטריוני החיפוש ושנמצאים גם בקרבת המסלול שצוין. פרטים נוספים זמינים במאמר בנושא חיפוש לאורך מסלול.

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

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