בקשה ותגובה ל-Minimum Matrix API

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

מבוא

בקשת API ל-Distance Matrix נראית כך:

https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters

הערך outputFormat יכול להיות אחד מהערכים הבאים:

  • ‫json (מומלץ) מציין פלט ב-JavaScript Object Notation ‏ (JSON).
  • ‫xml מציין שהפלט הוא XML.

חלק מהפרמטרים הם חובה וחלקם אופציונליים. כמו בכתובות URL רגילות, כל הפרמטרים מופרדים באמצעות התו אמפרסנד (&). כל התווים השמורים (לדוגמה, סימן הפלוס "+") חייבים להיות מקודדים בכתובת ה-URL. בהמשך מפורטים הפרמטרים והערכים האפשריים שלהם.

פרמטרים נדרשים

  • יעדים גיאוגרפיים

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

  • מקורות

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

    • מזהה מקום: אם מציינים מזהה מקום, צריך להוסיף לפניו את התחילית place_id:.
    • כתובת: אם מעבירים כתובת, השירות מבצע גיאו-קידוד של המחרוזת וממיר אותה לקואורדינטות של קו רוחב וקו אורך כדי לחשב את המרחק. יכול להיות שהקואורדינטה הזו שונה מזו שמוחזרת על ידי Geocoding API, למשל, כניסה לבניין במקום המרכז שלו.
      הערה: עדיף להשתמש במזהי מקומות מאשר בכתובות או בקואורדינטות של קו אורך וקו רוחב. שימוש בקואורדינטות תמיד יגרום לנקודה להיצמד לכביש הקרוב ביותר לקואורדינטות האלה – יכול להיות שזה לא יהיה שער הכניסה לנכס, או אפילו כביש שיוביל במהירות או בבטחה ליעד. השימוש בכתובת יספק את המרחק למרכז הבניין, ולא לכניסה לבניין.
    • קואורדינטות: אם מעבירים קואורדינטות של קו רוחב/אורך הן יוצמדו לכביש הקרוב ביותר. מומלץ להעביר מזהה מקום. אם אתם מעבירים קואורדינטות, ודאו שאין רווח בין ערכי קו הרוחב וקו האורך.
    • קודי Plus צריכים להיות בפורמט של קוד גלובלי או קוד מורכב. צריך להשתמש בפורמט של Plus Codes כמו בדוגמה הבאה (סימני הפלוס מקודדים ל-‎ %2B ורווחים מקודדים ל-‎ %20):
      • הקוד הגלובלי הוא קידומת אזורית בת 4 תווים וקוד מקומי בן 6 תווים או יותר (849VCWC8+R9 מקודד ל-849VCWC8%2BR9).
      • קוד מורכב הוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9 Mountain View, CA, USA מקודד ל-CWC8%2BR9%20Mountain%20View%20CA%20USA).
    • קו פוליגון מקודד לחלופין, אפשר לספק קבוצה מקודדת של קואורדינטות באמצעות אלגוריתם של קו פוליגון מקודד. השיטה הזו שימושית במיוחד אם יש לכם מספר גדול של נקודות מוצא, כי כתובת ה-URL קצרה משמעותית כשמשתמשים בקו פוליגוני מקודד.
      • לפני קווים פוליגוניים מקודדים צריך להוסיף את הקידומת enc: ואחריה נקודתיים :. לדוגמה: origins=enc:gfo}EtohhU:
      • אפשר גם לכלול כמה קווים שבורים מקודדים, ולהפריד ביניהם באמצעות התו של קו אנכי |. לדוגמה: 
        origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:

פרמטרים אופציונליים

  • arrival_time

    מציין את זמן ההגעה המועדף למסלול לתחבורה ציבורית, בשניות מאז חצות, 1 בינואר 1970 UTC. אפשר לציין departure_time או arrival_time, אבל לא את שניהם. הערה: הערך של arrival_time צריך להיות מספר שלם.

  • להימנע

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

    • ‫tolls מציין שהמסלול המחושב צריך להימנע מכבישי אגרה ומגשרים עם אגרה.
    • ‫highways מציין שהמסלול המחושב צריך להימנע מכבישים מהירים.
    • ‫ferries מציין שהמסלול המחושב צריך להימנע ממעבורות.
    • ‫indoor מציין שהמסלול המחושב צריך להימנע משימוש במדרגות בתוך מבנים במסלולי הליכה ומסלול לתחבורה ציבורית.

    אפשר לבקש מסלול שבו נמנעים משילוב כלשהו של כבישי אגרה, כבישים מהירים ומעבורות, על ידי העברת שתי ההגבלות לפרמטר avoid. לדוגמה avoid=tolls|highways|ferries.

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

  • departure_time

    מציינת את שעת היציאה המועדפת. אפשר לציין את השעה כמספר שלם בשניות מאז חצות, 1 בינואר 1970, שעון UTC. אם מציינים ערך של departure_time שגדול מ-9999-12-31T23:59:59.999999999Z, ה-API יחזיר את הערך 9999-12-31T23:59:59.999999999Z.departure_time לחלופין, אפשר לציין ערך של now, שיגדיר את שעת ההמראה לשעה הנוכחית (בדיוק של השנייה הקרובה ביותר). יכול להיות שזמן ההמראה יצוין בשני מקרים:

    • לגבי בקשות שבהן אמצעי התחבורה הוא תחבורה ציבורית: אפשר לציין אחת מהאפשרויות departure_time או arrival_time. אם לא מציינים את שני הזמנים, ברירת המחדל של departure_time היא הזמן הנוכחי (כלומר, ברירת המחדל של זמן ההמראה היא הזמן הנוכחי).
    • לגבי בקשות שבהן אמצעי התחבורה הוא נהיגה: אפשר לציין את departure_time כדי לקבל מסלול ומשך נסיעה (שדה התגובה: duration_in_traffic) שמתחשבים בתנאי התנועה. התאריך departure_time צריך להיות התאריך הנוכחי או תאריך עתידי. התאריך לא יכול להיות בעבר.
    הערה: אם לא מציינים את שעת היציאה, בחירת המסלול והמשך שלו מבוססים על רשת הכבישים ועל מצב התנועה הממוצע שלא תלוי בשעה. התוצאות של בקשה מסוימת עשויות להשתנות לאורך זמן בגלל שינויים ברשת הכבישים, עדכונים בממוצע מצב התנועה והאופי המבוזר של השירות. התוצאות עשויות להשתנות גם בין מסלולים כמעט שווים בכל זמן או תדירות.
    הערה: בקשות ל-Distance Matrix עם הפרמטרים departure_time ו-mode=driving מוגבלות ל-100 רכיבים לכל היותר בכל בקשה. מספר המקורות כפול מספר היעדים מגדיר את מספר הרכיבים.

  • language

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

    • כאן אפשר לעיין ברשימת השפות הנתמכות. ‫Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא מלאה.
    • אם לא מספקים את language, ה-API מנסה להשתמש בשפה המועדפת שצוינה בכותרת Accept-Language.
    • ה-API עושה כמיטב יכולתו כדי לספק כתובת רחוב שקלה לקריאה גם למשתמש וגם לתושבים המקומיים. כדי להשיג את המטרה הזו, הוא מחזיר כתובות רחוב בשפה המקומית, בתעתיק לכתב שהמשתמש יכול לקרוא אם צריך, בהתאם לשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מתוך הרכיב הראשון.
    • אם שם לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הקרובה ביותר.
    • לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שממשק ה-API בוחר להחזיר, ועל הסדר שבו הן מוחזרות. כלי להמרת כתובות לקואורדינטות (geocoder) מפרש קיצורים בצורה שונה בהתאם לשפה, כמו קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת. לדוגמה, utca ו-tér הן מילים נרדפות למילה 'רחוב' בהונגרית.

  • מצב

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

    • ‫driving (ברירת מחדל) מציין מסלולי נסיעה רגילים או מרחק באמצעות רשת הכבישים.
    • walking בקשות לקבלת מסלול הליכה או מרחק הליכה באמצעות שבילים להולכי רגל ומדרכות (אם יש כאלה).
    • ‫bicycling מבקש מסלול או מרחק לרכיבה על אופניים באמצעות שבילי אופניים ורחובות מועדפים (אם יש כאלה).
    • transit מבקש מסלול או מרחק באמצעות מסלולי תחבורה ציבורית (במקומות שבהם האפשרות זמינה). אם מגדירים את המצב לתחבורה ציבורית, אפשר לציין departure_time או arrival_time. אם לא מציינים את השעה, departure_time מוגדר כברירת מחדל לשעה הנוכחית (כלומר, שעת ההמראה מוגדרת כברירת מחדל לשעה הנוכחית). אפשר גם להוסיף transit_mode ו/או transit_routing_preference.
    הערה: לפעמים מסלולי הליכה ורכיבה על אופניים לא כוללים שבילים ברורים להולכי רגל או לרוכבי אופניים, ולכן התוצאות של המסלולים האלה יכללו אזהרות שצריך להציג למשתמש.
    הערה: נסיעות בתחבורה ציבורית זמינות עד 7 ימים אחורה או עד 100 ימים קדימה, בכפוף לזמינות המידע על התחבורה הציבורית שסופק על ידי ספקי הנתונים. לוחות הזמנים של התחבורה הציבורית משתנים לעיתים קרובות, יכול להיות שיהיו שינויים בנסיעות בתחבורה הציבורית לאורך זמן, ואין ערובה לכך שנקבל תוצאות עקביות לגבי תחזיות לטווח ארוך.

  • אזור

    קוד האזור, שמוגדר כערך ccTLD (דומיין ברמה העליונה) באורך שני תווים. רוב קודי ה-ccTLD זהים לקודי ISO 3166-1, אבל יש כמה יוצאים מן הכלל. לדוגמה, ה-ccTLD של בריטניה הוא uk (‎.co.uk), אבל קוד ISO 3166-1 שלה הוא gb (טכנית, עבור הישות 'ממלכת בריטניה הגדולה וצפון אירלנד').

  • traffic_model

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

    • ‫best_guess (ברירת מחדל) מציין שהערך של duration_in_traffic שמוחזר צריך להיות האומדן הכי טוב של זמן הנסיעה, בהתחשב בנתונים הידועים על מצב התנועה ההיסטורי ועל התנועה בזמן אמת. החשיבות של נתוני התנועה בזמן אמת גדלה ככל שהתאריך של departure_time קרוב יותר להיום.
    • ‫pessimistic מציין שהערך של duration_in_traffic שמוחזר צריך להיות ארוך יותר מזמן הנסיעה בפועל ברוב הימים, אבל יכול להיות שבימים מסוימים עם תנאי תנועה גרועים במיוחד הערך הזה יהיה גבוה יותר.
    • ‫optimistic מציין שהערך של duration_in_traffic שמוחזר צריך להיות קצר יותר מזמן הנסיעה בפועל ברוב הימים, אבל יכול להיות שבימים מסוימים עם תנאי תנועה טובים במיוחד, זמן הנסיעה יהיה קצר יותר מהערך הזה.

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

  • transit_mode

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

    • ‫bus מציין שהמסלול המחושב צריך לתת עדיפות לנסיעה באוטובוס.
    • ‫subway מציין שהמסלול המחושב צריך לתת עדיפות לנסיעה ברכבת תחתית.
    • ‫train מציין שחישוב המסלול צריך לתת עדיפות לנסיעה ברכבת.
    • ‫tram מציין שהמסלול המחושב צריך לתת עדיפות לנסיעה בחשמלית וברכבת קלה.
    • ‫rail מציין שהמסלול המחושב צריך לתת עדיפות לנסיעה ברכבת, בחשמלית, ברכבת קלה וברכבת תחתית. הפונקציה הזו שוות ערך ל-transit_mode=train|tram|subway.

  • transit_routing_preference

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

    • ‫less_walking מציין שהמסלול המחושב צריך להעדיף הליכה מוגבלת.
    • fewer_transfers מציין שהמסלול המחושב צריך להעדיף מספר מוגבל של החלפות.

  • יחידות

    מציינת את מערכת היחידות שבה יש להשתמש כשמציגים תוצאות.

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

דוגמאות לבקשות

בדוגמה הזו נעשה שימוש בקואורדינטות של קו רוחב וקו אורך כדי לציין את קואורדינטות היעד:

כתובת URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

בדוגמה הזו נעשה שימוש בקודי OLC כדי לציין את קואורדינטות היעד:

כתובת URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

בדוגמה הזו מוצגת אותה בקשה באמצעות קו פוליגוני מקודד:

כתובת URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

מידע על מצב התנועה

המידע על התנועה משמש כשכל התנאים הבאים מתקיימים (אלה התנאים שנדרשים כדי לקבל את השדה duration_in_traffic בתגובה של מטריצת מרחקים):

  • הפרמטר mode של הנסיעה הוא driving, או שלא צוין (driving הוא מצב הנסיעה שמוגדר כברירת מחדל).
  • הבקשה כוללת פרמטר departure_time תקין. אפשר להגדיר את departure_time לשעה הנוכחית או לשעה עתידית. התאריך לא יכול להיות בעבר.

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

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

כתובת URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

JSON

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins

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

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

הגדרת מסלולים מחושבים שחייבים לעבור בצד מסוים של הכביש

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

כתובת URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

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

כתובת URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

אפשר להשתמש במגביל side_of_road: רק עם ההגבלה הזו:

  • הערך של הפרמטר mode שמשויך לתחום 'נסיעות' הוא driving, או שלא צוין (driving הוא מצב הנסיעה שמוגדר כברירת מחדל).

הגדרת כיוון מסוים למסלולים מחושבים

כשמציינים מיקום, אפשר לבקש שהמסלול המחושב יעבור דרך המיקום בכיוון מסוים. הכותרת הזו מצוינת עם הקידומת heading=X:, כאשר X הוא ערך של מספר שלם בין 0 (כולל) ל-360 (לא כולל). כותרת של 0 מציינת צפון, 90 מציינת מזרח, וכן הלאה בכיוון השעון. לדוגמה, במסלול המחושב של הבקשה הזו, יוצאים מנקודת המוצא לכיוון מזרח ואז מבצעים פניית פרסה:

כתובת URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

אפשר להשתמש במילת ההתאמה heading=X: רק עם ההגבלות הבאות:

  • הפרמטר mode של נסיעות הוא driving,‏ bicycling או שלא צוין (driving הוא מצב הנסיעה שמוגדר כברירת מחדל).
  • המשנה side_of_road לא צוין לאותו מיקום.
  • המיקום מצוין באמצעות ערך של קו רוחב וקו אורך. אסור להשתמש ב-heading עם כתובות, מזהי מקומות או קווי פוליגון מקודדים.

בקשות ותשובות של Distance Matrix

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

כתובת URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco%7CVictoria%20BC
  &language=fr-FR
  &mode=bicycling
  &origins=Vancouver%20BC%7CSeattle
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'

הבקשה הזו תחזיר ארבעה אלמנטים – שני מקורות כפול שני יעדים:

ונקובר לסן פרנסיסקו ונקובר לוויקטוריה
מסיאטל לסן פרנסיסקו סיאטל לוויקטוריה

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

JSON

{
  "destination_addresses":
    ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"],
  "origin_addresses":
    ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "1 712 km", "value": 1711765 },
              "duration": { "text": "3 jours 16 heures", "value": 318119 },
              "status": "OK",
            },
            {
              "distance": { "text": "140 km", "value": 139695 },
              "duration": { "text": "6 heures 49 minutes", "value": 24567 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "1 452 km", "value": 1451704 },
              "duration": { "text": "3 jours 2 heures", "value": 266680 },
              "status": "OK",
            },
            {
              "distance": { "text": "146 km", "value": 146500 },
              "duration": { "text": "2 heures 53 minutes", "value": 10374 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km

DistanceMatrixResponse

שדה חובה סוג תיאור
חובה Array<string>

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

חובה Array<string>

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

חובה Array<DistanceMatrixRow>

מערך של רכיבים, שכל אחד מהם מכיל רכיב status, duration ו-distance.

מידע נוסף זמין במאמר DistanceMatrixRow.

חובה DistanceMatrixStatus

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

מידע נוסף זמין במאמר DistanceMatrixStatus.

אופציונלי מחרוזת

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

DistanceMatrixStatus

קודי סטטוס שמוחזרים על ידי השירות.

  • ‫OK מציין שהתשובה מכילה תוצאה תקינה.
  • ‫INVALID_REQUEST מציין שהבקשה שסופקה לא תקינה.
  • ‫MAX_ELEMENTS_EXCEEDED מציין שמספר המוצרים שמקורם ויעדם חורג מהמגבלה לכל שאילתה.
  • ‫MAX_DIMENSIONS_EXCEEDED מציין שמספר מקורות או היעדים חורג מהמגבלה לכל שאילתה.
  • הסמל OVER_DAILY_LIMIT מציין אחת מהאפשרויות הבאות:
    • מפתח ה-API חסר או לא תקין.
    • החיוב לא הופעל בחשבון שלך.
    • הייתה חריגה ממכסת שימוש שהוגדרה על ידי המשתמש.
    • אמצעי התשלום שצוין לא תקף יותר (לדוגמה, תוקף כרטיס האשראי פג).
  • ‫OVER_QUERY_LIMIT מציין שהשירות קיבל יותר מדי בקשות מהאפליקציה שלכם בפרק הזמן המותר.
  • ‫REQUEST_DENIED מציין שהשירות דחה את השימוש בשירות Distance Matrix על ידי האפליקציה שלכם.
  • ‫UNKNOWN_ERROR מציין שלא ניתן היה לעבד בקשה של מטריצת מרחקים בגלל שגיאת שרת. יכול להיות שהבקשה תצליח אם תנסו שוב.

DistanceMatrixRow

שדה חובה סוג תיאור
חובה מערך<DistanceMatrixElement>

כש-Distance Matrix API מחזיר תוצאות, הוא ממקם אותן במערך שורות בפורמט JSON. גם אם לא מוחזרות תוצאות (למשל, אם המקורות או היעדים לא קיימים), עדיין מוחזר מערך ריק.

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

כל מערך שורות מכיל רשומה אחת או יותר של רכיבים, שבתורה מכילה את המידע על זוג אחד של מקור ויעד.

מידע נוסף זמין במאמר DistanceMatrixElement.

DistanceMatrixElement

שדה חובה סוג תיאור
חובה DistanceMatrixElementStatus

סטטוס של הרכיב.

מידע נוסף זמין במאמר בנושא DistanceMatrixElementStatus.

אופציונלי TextValueObject

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

מידע נוסף זמין במאמר בנושא TextValueObject.

אופציונלי TextValueObject

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

מידע נוסף זמין במאמר בנושא TextValueObject.

אופציונלי TextValueObject

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

  • הבקשה כוללת את הפרמטר departure_time.
  • מצב התנועה זמין במסלול המבוקש.
  • פרמטר המצב מוגדר לנהיגה.

מידע נוסף זמין במאמר בנושא TextValueObject.

אופציונלי מחיר הכרטיס

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

מידע נוסף זמין במאמר בנושא תעריפים.

מחיר הכרטיס

המחיר הכולל של הכרטיס למסלול.

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}
שדה חובה סוג תיאור
חובה מחרוזת

קוד מטבע בהתאם לתקן ISO 4217 שמציין את המטבע שבו הסכום מוצג.

text

חובה מחרוזת

סכום התעריף הכולל, בפורמט של השפה המבוקשת.
חובה number

סכום מחיר הכרטיס הכולל, במטבע שצוין.

DistanceMatrixElementStatus

  • ‫OK מציין שהתשובה מכילה תוצאה תקינה.
  • ‫NOT_FOUND מציין שלא ניתן לבצע גיאו-קידוד של המקור או היעד של צמד המיקומים הזה.
  • ‫ZERO_RESULTS מציין שלא נמצא מסלול בין נקודת המוצא ליעד.
  • MAX_ROUTE_LENGTH_EXCEEDED מציין שהמסלול המבוקש ארוך מדי ואי אפשר לעבד אותו.

TextValueObject

אובייקט שמכיל ערך מספרי וייצוג טקסטואלי שלו בפורמט.

שדה חובה סוג תיאור

text

חובה מחרוזת

ערך מחרוזת.
חובה number

ערך מספרי.