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

מפתחים באזור הכלכלי האירופי (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) וב-method‏ ComputeRoutes, השליטה מתבצעת באמצעות polylineEncoding.

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

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

    ב-method‏ computeRoutes (REST) וב-method‏ 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();