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

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

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

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

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

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

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

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

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

    בשיטה computeRoutes (REST) וב-ComputeRoutes, השליטה מתבצעת באמצעות polylineEncoding.

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

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

    בשיטה 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 Text Search כדי לחפש לאורך מסלול מחושב. מעבירים את קו הפוליגון המקודד של מסלול שחושב מראש מ-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();