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

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

דף זה מתאר את השירות בצד הלקוח הזמין באמצעות Maps JavaScript API. אם אתם רוצים לעבוד עם שירותי האינטרנט של מפות Google בשרת שלכם, תוכלו לעיין בלקוח Node.js עבור שירותי מפות Google. הדף באותו קישור כולל גם את לקוח Java, את לקוח Python ול-Go Client עבור שירותי מפות Google.

סקירה כללית

אפשר גם לעיין בהפניה ל-API של מפות Google: מטריצת מרחק

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

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

איך מתחילים

לפני השימוש בשירות 'מטריצת מרחק' בממשק ה-API של מפות Google JavaScript, יש לוודא שה-API של מטריצת המרחק מופעל ב-Google Cloud Console, באותו פרויקט שהגדרת ל-Maps JavaScript API.

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

1. נכנסים ל- Google Cloud Console.
2. לוחצים על הלחצן Select a project, בוחרים את הפרויקט שהגדרתם ב-Maps JavaScript API ולוחצים על Open.
3. ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את DISTANCE Matrix API.
4. אם ה-API מופיע ברשימה, הכול מוכן. אם ה-API לא מופיע, מפעילים אותו:
   1. בחלק העליון של הדף, בוחרים באפשרות הפעלת API כדי להציג את הכרטיסייה ספרייה. לחלופין, בתפריט שמימין בוחרים באפשרות ספרייה.
   2. מחפשים את המרחק מטריצת API ובוחרים אותו מרשימת התוצאות.
   3. לוחצים על הפעלה. בסיום התהליך, המרחק מטריצת מופיע ברשימת ממשקי ה-API ב מרכז הבקרה.

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

תמחור

ב-16 ביולי 2018 תיכנס לתוקף תוכנית תמחור חדשה מסוג 'תשלום לפי שימוש' עבור מפות Google, מסלולים ומקומות. מידע נוסף על המגבלות החדשות ועל השימוש במגבלות השימוש בשירות מטריצת המרחקים של JavaScript מפורט במאמר שימוש וחיוב ב-API של מטריצת המרחקים.

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

מדיניות

השימוש בשירות 'מטריצת מרחק' חייב להיות בהתאם למדיניות שמפורטת עבור ה-API של מטריצת המרחקים.

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

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

ניתן לגשת לשירות מטריצת המרחק שבתוך הקוד דרך אובייקט הבנייה google.maps.DistanceMatrixService. השיטה DistanceMatrixService.getDistanceMatrix() מפעילה בקשה לשירות מטריצת המרחקים ומעבירה אותה ליטרל של אובייקט DistanceMatrixRequest שמכיל את המקורות, היעדים ומצב הנסיעה, וגם שיטה לקריאה חוזרת (callback) עם קבלת התגובה.

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 או אובייקט המשמשים לחישוב המרחק והזמן.
• 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 Maps Platform Premium, הלקוחות שלנו היו בעבר הדרך המומלצת לציין אם התוצאה צריכה לכלול משך זמן שמביא בחשבון את מצב התנועה הנוכחי. עכשיו צריך להשתמש בשדה drivingOptions.

אמצעי הגעה

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

• BICYCLING מבקש מסלולי אופניים באמצעות שבילי אופניים ורחובות מועדפים (כרגע זמין רק בארה & quot;ב ובערים מסוימות בקנדה).
• 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 של בקשת מטריצת המרחקים. הכתובות מוחזרות כי הפורמט שלהן נקבע על ידי המקודד.
• destinationAddresses הוא מערך המכיל את המיקומים שהועברו בשדה destinations, בפורמט שהוחזר על ידי המקודד.
• rows הוא מערך של DistanceMatrixResponseRow אובייקטים, כאשר כל שורה תואמת למקור.
• elements הם צאצאים של rows, והם תואמים להתאמה של מקור השורה עם כל יעד. הם כוללים סטטוס, משך זמן, מרחק וסכום נסיעה (אם זמין) לכל צמד של מקור/יעד.
• כל element מכיל את השדות הבאים:
  • status: רשימה של קודי סטטוס אפשריים מופיעה בקטע קודי סטטוס.
  • duration: משך הזמן שלוקח לנסוע במסלול הזה, בשניות. (השדה value) וכן text. הפורמט של ערך הטקסט תואם לunitSystem שצוין בבקשה (או במדד, אם לא צוינה העדפה).
  • duration_in_traffic: משך הזמן שלוקח לנסוע במסלול הזה, תוך התייחסות לתנאי התנועה הנוכחיים, שצוינו בשניות (השדה value) וכן text. הפורמט של ערך הטקסט תואם לunitSystem שצוין בבקשה (או במדד, אם לא צוינה העדפה). המוצר duration_in_traffic מוחזר רק ללקוחות בתוכנית הפרימיום של מפות Google, שבהם נתוני התנועה זמינים, הערך 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];
      }
    }
  }
}