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

מפתחים באזור הכלכלי האירופי (EEA)
הערה: ספריות בצד השרת

סקירה כללית

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

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

תחילת העבודה

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

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

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

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

תמחור

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

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

מדיניות

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

בקשות ל-Distance Matrix

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

אתם ניגשים לשירות Distance Matrix בקוד באמצעות אובייקט ה-constructor‏ google.maps.DistanceMatrixService. ה-method‏ DistanceMatrixService.getDistanceMatrix() יוזמת בקשה לשירות Distance Matrix, ומעבירה אליו ליטרל של אובייקט 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, המסלולים בין הנקודות יחושבו תוך שימוש במסלולים ללא אגרה, בכל מקום שאפשר.

מצבי נסיעה

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

  • ‫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'
  }
}

תשובות של Distance Matrix API

קריאה מוצלחת לשירות Distance Matrix מחזירה אובייקט 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"
      }
    } ]
  } ]
}

תוצאות של Distance Matrix

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

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

קודי סטטוס

התשובה של Distance Matrix כוללת קוד סטטוס לתשובה כולה, וגם סטטוס לכל רכיב.

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

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

  • ‫OK – הבקשה תקפה. יכול להיות שהסטטוס הזה יוחזר גם אם לא נמצאו מסלולים בין אף אחד מהיעדים לבין אף אחד מהמקורות. מידע על הסטטוס ברמת הרכיב מופיע במאמר קודי סטטוס של רכיבים.
  • ‫INVALID_REQUEST — הבקשה שסופקה לא תקינה. הסיבה לכך היא בדרך כלל שחסרים שדות חובה. לרשימת השדות הנתמכים
  • MAX_ELEMENTS_EXCEEDED — מכפלת המקורות והיעדים חורגת מהמגבלה לכל שאילתה.
  • ‫MAX_DIMENSIONS_EXCEEDED — הבקשה שלך הכילה יותר מ-25 מקורות או יותר מ-25 יעדים.
  • ‫OVER_QUERY_LIMIT – הבקשה שלך מכילה יותר מדי אלמנטים בפרק הזמן המותר. הבקשה אמורה להצליח אם תנסו שוב אחרי פרק זמן סביר.
  • ‫REQUEST_DENIED — השירות דחה את השימוש בשירות Distance Matrix בדף האינטרנט שלכם.
  • ‫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];
      }
    }
  }
}