‫ קבלת Maps Demo Key: אתם יכולים לנסות תכונות נבחרות של Maps JavaScript API ו-Places UI Kit ללא עלות באמצעות Maps Demo Key – בלי להזין פרטי חיוב.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

שירות מטריצת מרחקים (דור קודם)

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

הערה: ספריות בצד השרת

סקירה כללית

שירות מטריצת מרחקים של Google מחשב את מרחק הנסיעה ואת משך הנסיעה בין כמה נקודות מוצא ויעדים, בהתאם לאמצעי התחבורה שנבחר.

השירות הזה לא מחזיר מידע מפורט על המסלול. כדי לקבל מידע על מסלול, כולל קווים פוליגוניים והוראות טקסטואליות, אפשר להעביר את נקודת המוצא והיעד הרצויות ל-Directions Service.

תחילת העבודה

לפני שמשתמשים בשירות מטריצת מרחקים ב-Maps JavaScript API, צריך לוודא ש-Distance Matrix API (הדור הקודם) מופעל במסוף Google Cloud, באותו פרויקט שהגדרתם ל-Maps JavaScript API.

כדי לראות את רשימת ממשקי ה-API שמופעלים:

נכנסים ל מסוף Google Cloud.
לוחצים על הכפתור Select a project, בוחרים את הפרויקט שהגדרתם ל-Maps JavaScript API ולוחצים על Open.
ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Distance Matrix API (Legacy)‎.
אם ה-API מופיע ברשימה, אתם מוכנים. אם ה-API לא מופיע ברשימה, מפעילים אותו בכתובת https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com

תמחור ומדיניות

תמחור

כדי לקבל מידע על מדיניות התמחור והשימוש בשירות מטריצת המרחקים של JavaScript, קראו את המאמר שימוש וחיוב של Distance Matrix API (דור קודם).

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

מדיניות

השימוש בשירות Distance Matrix צריך להיות בהתאם לכללי המדיניות שמתוארים לגבי Distance Matrix API (דור קודם).

בקשות ל-Distance Matrix

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

כדי לגשת לשירות מטריצת מרחקים בקוד, משתמשים באובייקט ה-constructor‏ google.maps.DistanceMatrixService. ה-method‏ DistanceMatrixService.getDistanceMatrix() יוזמת בקשה לשירות מטריצת מרחקים, ומעבירה לו ליטרל של אובייקט DistanceMatrixRequest שמכיל את נקודות המוצא, היעדים ואמצעי ההגעה, וגם שיטת קריאה חוזרת להפעלה אחרי קבלת התשובה.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

להצגת דוגמה

ה-DistanceMatrixRequest מכיל את השדות הבאים:

origins (חובה) – מערך שמכיל מחרוזת אחת או יותר של כתובות, אובייקטים מסוג google.maps.LatLng או אובייקטים מסוג Place, שמהם מחושבים המרחק והזמן.
‫destinations (חובה) – מערך שמכיל מחרוזת אחת או יותר של כתובות, אובייקטים מסוג google.maps.LatLng או אובייקטים מסוג Place, שלגביהם צריך לחשב את המרחק ומשך הנסיעה.
travelMode (אופציונלי) — אמצעי התחבורה שבו משתמשים כשמחשבים מסלול. עיינו בקטע בנושא אמצעי תחבורה.
‫transitOptions (אופציונלי) – אפשרויות שרלוונטיות רק לבקשות שבהן הערך של travelMode הוא TRANSIT. הערכים התקינים מתוארים בקטע על אפשרויות הובלה.
‫drivingOptions (אופציונלי) מציין ערכים שחלים רק על בקשות שבהן travelMode הוא DRIVING. הערכים התקינים מתוארים בקטע אפשרויות נהיגה.
‫unitSystem (אופציונלי) – מערכת היחידות שבה משתמשים כדי להציג את המרחק. הערכים הקבילים הם:
- ‫google.maps.UnitSystem.METRIC (ברירת מחדל)
- google.maps.UnitSystem.IMPERIAL
‫avoidHighways (אופציונלי) – אם הערך הוא true, המסלולים בין נקודות המוצא והיעד יחושבו כך שיימנעו מכבישים מהירים ככל האפשר.
‫avoidTolls (אופציונלי) – אם הערך הוא true, המסלולים בין הנקודות יחושבו באמצעות מסלולים ללא אגרה, ככל האפשר.

הערה: השדה durationInTraffic יצא משימוש. בעבר, זו הייתה הדרך המומלצת ללקוחות של מינוי פרימיום לפלטפורמה של מפות Google לציין אם התוצאה צריכה לכלול משך זמן שמביא בחשבון את מצב התנועה הנוכחי. עכשיו צריך להשתמש בשדה drivingOptions במקום זאת.

אמצעי הגעה

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

‫BICYCLING מבקש מסלול אופניים דרך שבילי אופניים ורחובות מועדפים (כרגע זמין רק בארה "ב ובחלק מהערים בקנדה).
‫DRIVING (ברירת המחדל) מציין מסלול נסיעה רגיל באמצעות רשת הכבישים.
TRANSIT מבקש מסלולים בתחבורה ציבורית. אפשר לציין את האפשרות הזו רק אם הבקשה כוללת מפתח API. בקטע אפשרויות תחבורה ציבורית מפורטות האפשרויות הזמינות בבקשה מהסוג הזה.
‫WALKING מבקש מסלול הליכה דרך שבילים להולכי רגל ומדרכות (אם יש כאלה).

אפשרויות תחבורה ציבורית

שירות התחבורה הציבורית נמצא כרגע בשלב ניסיוני. בשלב הזה, נטמיע הגבלות קצב של יצירת בקשות כדי למנוע ניצול לרעה של ה-API. בסופו של דבר, נאכוף מגבלה על מספר השאילתות הכולל לכל טעינת מפה, בהתאם לשימוש הוגן ב-API.

האפשרויות הזמינות לבקשה של מטריצת מרחקים משתנות בהתאם לאמצעי התחבורה. בבקשות לתחבורה ציבורית, המערכת מתעלמת מהאפשרויות avoidHighways ו-avoidTolls. אפשר לציין אפשרויות ניתוב ספציפיות לתחבורה ציבורית באמצעות הליטרל של האובייקט TransitOptions.

בקשות למעבר הן תלויות זמן. החישובים יוחזרו רק לזמנים עתידיים.

הליטרל של האובייקט TransitOptions מכיל את השדות הבאים:

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

השדות האלה מוסברים בהמשך:

arrivalTime (אופציונלי) מציין את זמן ההגעה הרצוי כאובייקט Date. אם מציינים את זמן ההגעה, המערכת מתעלמת מזמן היציאה.
‫departureTime (אופציונלי) מציין את זמן היציאה הרצוי כאובייקט Date. המערכת תתעלם מהערך של departureTime אם צוין הערך של arrivalTime. אם לא מציינים ערך ל-departureTime או ל-arrivalTime, ברירת המחדל היא הזמן הנוכחי.
‫modes (אופציונלי) הוא מערך שמכיל ליטרל אחד או יותר של אובייקט TransitMode. אפשר לכלול את השדה הזה רק אם הבקשה כוללת מפתח API. כל TransitMode מציין אמצעי תחבורה מועדף. אלה הערכים המותרים:
- ‫BUS מציין שהמסלול המחושב צריך להעדיף נסיעה באוטובוס.
- ‫RAIL מציין שהמסלול המחושב צריך להעדיף נסיעה ברכבת, בחשמלית, ברכבת קלה וברכבת תחתית.
- SUBWAY מציין שהמסלול המחושב צריך להעדיף נסיעה ברכבת תחתית.
- TRAIN מציין שהמסלול המחושב צריך להעדיף נסיעה ברכבת.
- TRAM מציין שהמסלול המחושב צריך להעדיף נסיעה בחשמלית וברכבת קלה.
‫routingPreference (אופציונלי) מציין העדפות למסלולי תחבורה ציבורית. באמצעות האפשרות הזו, אתם יכולים להטות את האפשרויות שמוחזרות, במקום לקבל את המסלול הטוב ביותר שמוגדר כברירת מחדל ונבחר על ידי ה-API. אפשר לציין את השדה הזה רק אם הבקשה כוללת מפתח API. אלה הערכים המותרים:
- FEWER_TRANSFERS מציין שהמסלול המחושב צריך להעדיף מספר מוגבל של החלפות.
- LESS_WALKING מציין שהמסלול המחושב צריך להעדיף כמויות מוגבלות של הליכה.

אפשרויות לגבי נהיגה

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

האובייקט drivingOptions מכיל את השדות הבאים:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

השדות האלה מוסברים בהמשך:

‫departureTime (חובה כדי שהליטרל של האובייקט drivingOptions יהיה תקין) מציין את שעת היציאה הרצויה כאובייקט Date. הערך צריך להיות מוגדר לשעה הנוכחית או לשעה כלשהי בעתיד. התאריך לא יכול להיות בעבר. (ה-API ממיר את כל התאריכים ל-UTC כדי להבטיח טיפול עקבי בכל אזורי הזמן). אם כוללים את הפרמטר departureTime בבקשה, ה-API מחזיר את המסלול הטוב ביותר בהתאם למצב התנועה הצפוי באותו זמן, וכולל בתשובה את זמן הנסיעה החזוי בהתאם למצב התנועה (duration_in_traffic). אם לא מציינים שעת יציאה (כלומר, אם הבקשה לא כוללת את drivingOptions), המסלול שמוחזר הוא בדרך כלל מסלול טוב שלא מביא בחשבון את מצב התנועה.
זהירות: אם לא מציינים שעת יציאה, המסלול ומשך הזמן שנבחרים מבוססים על רשת הכבישים ועל מצב התנועה הממוצע ללא תלות בזמן, ולא על מצב הדרך הנוכחי. לכן, יכול להיות שהמסלולים יכללו כבישים שסגורים באופן זמני. התוצאות של בקשה מסוימת עשויות להשתנות עם הזמן בגלל שינויים ברשת הכבישים, עדכונים במצב התנועה הממוצע והאופי המבוזר של השירות. יכול להיות גם שהתוצאות יהיו שונות בין מסלולים כמעט זהים בכל זמן או תדירות.
trafficModel (אופציונלי) מציין את ההנחות שבהן צריך להשתמש כשמחשבים את הזמן בתנועה. ההגדרה הזו משפיעה על הערך שמוחזר בשדה duration_in_traffic בתגובה, שמכיל את זמן הנסיעה החזוי בהתאם לממוצעים היסטוריים. ברירת המחדל היא best_guess. אלה הערכים המותרים:
- ‫bestguess (ברירת המחדל) מציין שהערך המוחזר של duration_in_traffic צריך להיות האומדן הטוב ביותר של זמן ההגעה, בהתאם למידע הידוע על מצב התנועה ההיסטורי ועל מצב התנועה בזמן אמת. ככל שdepartureTime קרוב יותר לעכשיו, כך יש חשיבות רבה יותר לתנועה בזמן אמת.
- pessimistic מציין שהערך של duration_in_traffic שמוחזר צריך להיות ארוך יותר מזמן ההגעה בפועל ברוב הימים, אבל יכול להיות שבימים מסוימים עם מצב תנועה גרוע במיוחד, זמן ההגעה בפועל יהיה ארוך יותר מהערך הזה.
- optimistic מציין שהערך המוחזר של duration_in_traffic צריך להיות קצר יותר מזמן ההגעה בפועל ברוב הימים, אבל יכול להיות שבימים מסוימים מצב התנועה יהיה טוב במיוחד והנסיעה תהיה מהירה יותר מהערך הזה.

למטה מוצגת דוגמה ל-DistanceMatrixRequest למסלולי נסיעה, כולל שעת יציאה ומודל תנועה:

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

תגובות של מטריצת מרחקים

קריאה מוצלחת לשירות מטריצת מרחקים מחזירה אובייקט DistanceMatrixResponse ואובייקט DistanceMatrixStatus. הם מועברים לפונקציית הקריאה החוזרת שציינתם בבקשה.

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

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

תוצאות של מטריצת מרחקים

השדות הנתמכים בתגובה מוסברים בהמשך.

‫originAddresses הוא מערך שמכיל את המיקומים שהועברו בשדה origins של הבקשה ל-מטריצת מרחקים. הכתובות מוחזרות בפורמט שנקבע על ידי הכלי להמרת כתובות לקואורדינטות (geocoder).
‫destinationAddresses הוא מערך שמכיל את המיקומים שהועברו בשדה destinations, בפורמט שהוחזר על ידי הכלי להמרת כתובות לקואורדינטות (geocoder).
‫rows הוא מערך של אובייקטים מסוג DistanceMatrixResponseRow, וכל שורה תואמת למקור.
‫elements הם צאצאים של rows, והם תואמים לשילוב של מקור השורה עם כל יעד. הם מכילים מידע על הסטטוס, משך הנסיעה, המרחק והמחיר (אם זמין) לכל צמד של נקודת מוצא ויעד.
כל element מכיל את השדות הבאים:
- ‫status: רשימה של קודי סטטוס אפשריים מופיעה בקטע קודי סטטוס.
- ‫duration: משך הזמן שלוקח לעבור את המסלול הזה, בשניות (השדה value) ובפורמט text. הערך הטקסטואלי מעוצב לפי unitSystem שצוינה בבקשה (או לפי השיטה המטרית, אם לא צוינה העדפה).
- ‫duration_in_traffic: משך הזמן שלוקח לעבור את המסלול הזה, בהתחשב במצב התנועה הנוכחי, בשניות (השדה value) וכtext. הערך הטקסטואלי מעוצב לפי ה-unitSystem שצוין בבקשה (או לפי השיטה המטרית, אם לא צוינה העדפה). השדה duration_in_traffic מוחזר רק אם יש נתוני תנועה, השדה mode מוגדר כ-driving, והשדה departureTime נכלל כחלק מהשדה distanceMatrixOptions בבקשה.
- ‫distance: המרחק הכולל של המסלול, במטרים (value) וכמחרוזת (text). הערך הטקסטואלי מעוצב לפי unitSystem שצוינה בבקשה (או לפי השיטה המטרית, אם לא צוינה העדפה).
- ‫fare: מכיל את מחיר הנסיעה הכולל (כלומר, העלות הכוללת של הכרטיסים) במסלול הזה. המאפיין הזה מוחזר רק לבקשות של תחבורה ציבורית ורק לספקי תחבורה ציבורית שבהם מידע על תעריפים זמין. המידע כולל:
  - ‫currency: קוד מטבע בתקן ISO 4217 שמציין את המטבע שבו הסכום מבוטא.
  - ‫value: הסכום הכולל של התעריף, במטבע שצוין למעלה.

קודי סטטוס

התשובה של מטריצת מרחקים כוללת קוד סטטוס לתשובה כולה, וגם סטטוס לכל רכיב.

קודי סטטוס של תגובות

קודי הסטטוס שרלוונטיים ל-DistanceMatrixResponse מועברים באובייקט DistanceMatrixStatus וכוללים את:

‫OK – הבקשה תקינה. הסטטוס הזה יכול לחזור גם אם לא נמצאו מסלולים בין אף אחד מנקודות המוצא והיעדים. בקטע קודי סטטוס של רכיבים מפורט מידע על סטטוסים ברמת הרכיב.
‫INVALID_REQUEST – הבקשה שנשלחה לא הייתה תקינה. לרוב זה קורה כי חסרים שדות חובה. לרשימת השדות הנתמכים
‫MAX_ELEMENTS_EXCEEDED – המכפלה של נקודות המוצא והיעדים חורגת מהמגבלה לכל שאילתה.
‫MAX_DIMENSIONS_EXCEEDED – הבקשה הכילה יותר מ-25 נקודות מוצא או יותר מ-25 יעדים.
‫OVER_QUERY_LIMIT – האפליקציה ביקשה יותר מדי רכיבים בפרק הזמן המותר. הבקשה אמורה להצליח אם תנסו שוב אחרי פרק זמן סביר.
‫REQUEST_DENIED – השירות דחה את השימוש של דף האינטרנט בשירות מטריצת מרחקים.
UNKNOWN_ERROR – לא ניתן היה לעבד בקשה של מטריצת מרחקים בגלל שגיאה בחיבור לשרת. יכול להיות שהבקשה תצליח אם תנסו שוב.

קודי סטטוס של רכיבים

קודי הסטטוס הבאים חלים על אובייקטים ספציפיים של DistanceMatrixElement:

‫NOT_FOUND – לא ניתן היה להמיר לקואורדינטות את המקור ו/או היעד של הצמד הזה.
‫OK – התשובה מכילה תוצאה תקינה.
‫ZERO_RESULTS – לא נמצא מסלול בין נקודת המוצא ליעד.

ניתוח התוצאות

האובייקט DistanceMatrixResponse מכיל row אחד לכל מקור שהועבר בבקשה. כל שורה מכילה שדה element לכל התאמה של נקודת המוצא הזו עם היעדים שצוינו.

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}