המוצר הזה נמצא בסטטוס מדור קודם. החל מאוקטובר 2026, אי אפשר יותר להפעיל את Distance Matrix API (גרסה קודמת) בפרויקטים חדשים ב-Google Cloud. הפרויקטים הקיימים ממשיכים להיות נתמכים באופן מלא. כדי ליהנות מתכונות חדשות וביצועים משופרים, כדאי לעבור ל-Routes API.

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

בקשה ותגובה של Distance Matrix API (מדור קודם)

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

מבוא

בקשה ל-Distance Matrix API (דור קודם) נראית כך:

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

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

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

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

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

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

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

נקודת ההתחלה לחישוב מרחק הנסיעה וזמן הנסיעה. אפשר לציין מיקום אחד או יותר, מופרדים בתו קו אנכי (|), בפורמט של מזהה מקום, כתובת או קואורדינטות של קו רוחב/קו אורך:
- מזהה מקום: אם אתם מספקים מזהה מקום, אתם צריכים להוסיף לו את התחילית place_id:.
- כתובת: אם מעבירים כתובת, השירות ממיר את המחרוזת לקואורדינטות של קו רוחב/קו אורך כדי לחשב את המרחק. יכול להיות שהקואורדינטה הזו תהיה שונה מזו שמוחזרת על ידי Geocoding API, למשל כניסה לבניין במקום מרכז הבניין.
  הערה: עדיף להשתמש במזהי מקומות ולא בכתובות או בקואורדינטות של קו רוחב/קו אורך. אם משתמשים בקואורדינטות, הנקודה תמיד תתחבר לכביש הקרוב ביותר לקואורדינטות האלה, אבל יכול להיות שזה לא יהיה כביש גישה לנכס, או אפילו כביש שיוביל ליעד במהירות או בבטחה. אם משתמשים בכתובת, המרחק שמוצג הוא למרכז המבנה, ולא לכניסה למבנה.
- קואורדינטות: אם מעבירים קואורדינטות של קו רוחב/קו אורך, הן יתחברו לכביש הקרוב ביותר. עדיף להעביר מזהה מקום. אם אתם מעבירים קואורדינטות, ודאו שאין רווח בין ערכי קו הרוחב וקו האורך.
- קודי Plus Code צריכים להיות בפורמט של קוד גלובלי או קוד מורכב. צריך להזין את ה-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 יחזיר את departure_time ל-9999-12-31T23:59:59.999999999Z. אפשר גם לציין את הערך now, שמגדיר את זמן היציאה לשעה הנוכחית (עד לרמת דיוק של שנייה). אפשר לציין את שעת היציאה בשני מקרים:
- בבקשות שבהן אמצעי התחבורה הוא תחבורה ציבורית: אפשר לציין את departure_time או את arrival_time. אם לא מציינים אף אחת מהשעות, הערך של departure_time מוגדר כברירת מחדל לעכשיו (כלומר, שעת היציאה מוגדרת כברירת מחדל לשעה הנוכחית).
- בבקשות שבהן אמצעי התחבורה הוא נהיגה: אפשר לציין את departure_time כדי לקבל מסלול ומשך נסיעה (שדה התגובה: duration_in_traffic) שמביאים בחשבון את מצב התנועה. השדה departure_time חייב להיות מוגדר לשעה הנוכחית או לשעה כלשהי בעתיד. התאריך לא יכול להיות בעבר.
הערה: אם לא צוינה שעת יציאה, בחירת המסלול ומשך הנסיעה מבוססים על רשת הכבישים ועל מצב התנועה הממוצע ללא תלות בזמן. התוצאות של בקשה מסוימת עשויות להשתנות עם הזמן בגלל שינויים ברשת הכבישים, עדכונים במצב התנועה הממוצע והאופי המבוזר של השירות. התוצאות עשויות להשתנות גם בין מסלולים כמעט זהים בכל זמן או תדירות.

הערה: בקשות של מטריצת מרחקים שמציינות את departure_time כש-mode=driving מוגבלות ל-100 רכיבים לכל היותר לכל בקשה. מספר נקודות המוצא כפול מספר היעדים מגדיר את מספר הרכיבים.
language

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

כדי לחשב מרחקים ומסלולים, אתם יכולים לציין את אמצעי ההגעה שבו אתם רוצים להשתמש. כברירת מחדל, המערכת משתמשת במצב DRIVING. כברירת מחדל, המסלולים מחושבים כמסלולי נסיעה. אפשר להשתמש באמצעי התחבורה הבאים:
- ‫driving (ברירת המחדל) מציין מסלול נסיעה רגיל או מרחק באמצעות רשת הכבישים.
- ‫walking מבקש מסלול הליכה או מרחק באמצעות שבילים להולכי רגל ומדרכות (אם יש).
- ‫bicycling מבקש מסלול רכיבה על אופניים או מרחק באמצעות שבילי אופניים ורחובות מועדפים (אם הם זמינים).
- ‫transit מבקש מסלולים או מרחק באמצעות מסלולי תחבורה ציבורית (אם זמינים). אם מגדירים את המצב ל-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'

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

כתובת 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 הבאה יוזמת בקשה ל-Distance Matrix למרחקי נסיעה בין בוסטון, מסצ'וסטס או צ'רלסטאון, מסצ'וסטס, לבין לקסינגטון, מסצ'וסטס וקונקורד, מסצ'וסטס. הבקשה כוללת שעת יציאה, ועומדת בכל הדרישות להחזרת השדה 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 עם כתובות, מזהי מקומות או קווים פוליגוניים מקודדים.

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

למטה מוצגת בקשת 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

שדה	חובה	סוג	תיאור
`destination_addresses`	חובה	מערך<string>	מערך של כתובות שהוחזרו על ידי ה-API מהבקשה המקורית. כמו ב-`origin_addresses`, גם כאן מתבצעת התאמה לשוק המקומי, אם צריך. התוכן הזה מיועד לקריאה כמו שהוא. אל תנתחו באופן פרוגרמטי את הכתובות המעוצבות.
`origin_addresses`	חובה	מערך<string>	מערך של כתובות שהוחזרו על ידי ה-API מהבקשה המקורית. הכתובות האלה מעוצבות על ידי הכלי להמרת כתובות לקואורדינטות (geocoder) ומותאמות לשפה המקומית בהתאם לפרמטר השפה שנשלח עם הבקשה. התוכן הזה מיועד לקריאה כמו שהוא. אל תנתחו באופן פרוגרמטי את הכתובות המעוצבות.
`rows`	חובה	Array<DistanceMatrixRow>	מערך של רכיבים, שכל אחד מהם מכיל את הרכיבים `status`,‏ `duration` ו-`distance`. מידע נוסף זמין במאמר DistanceMatrixRow.
`status`	חובה	DistanceMatrixStatus	מכיל את סטטוס הבקשה, ויכול להכיל מידע על תוצאות ניפוי הבאגים כדי לעזור לכם להבין למה הבקשה נכשלה. מידע נוסף זמין במאמר DistanceMatrixStatus.
`error_message`	אופציונלי	מחרוזת	מחרוזת שמכילה את הטקסט הקריא לאנשים של כל השגיאות שנתקלו בהן במהלך עיבוד הבקשה.

DistanceMatrixStatus

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

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

DistanceMatrixRow

שדה	חובה	סוג	תיאור
`elements`	חובה	Array<DistanceMatrixElement>	כשה-Distance Matrix API מחזיר תוצאות, הוא ממקם אותן במערך שורות בפורמט JSON. גם אם לא מוחזרות תוצאות (למשל, כשנקודות המוצא ו/או היעדים לא קיימים), עדיין מוחזר מערך ריק. השורות מסודרות לפי הערכים בפרמטר המקור של הבקשה. כל שורה תואמת לנקודת מוצא, וכל רכיב בשורה הזו תואם להתאמה בין נקודת המוצא לבין ערך של יעד. כל מערך שורות מכיל רשומת רכיב אחת או יותר, שבתורן מכילות את המידע על זוג אחד של מוצא ויעד. מידע נוסף זמין במאמר DistanceMatrixElement.

DistanceMatrixElement

שדה	חובה	סוג	תיאור
`status`	חובה	DistanceMatrixElementStatus	סטטוס של הרכיב. מידע נוסף זמין במאמר DistanceMatrixElementStatus.
`distance`	אופציונלי	TextValueObject	המרחק הכולל של המסלול הזה, מבוטא במטרים (ערך) וכטקסט. הערך הטקסטואלי משתמש במערכת היחידות שצוינה בפרמטר unit של הבקשה המקורית, או באזור של נקודת המוצא. מידע נוסף זמין במאמר TextValueObject.
`duration`	אופציונלי	TextValueObject	משך הזמן שנדרש כדי לעבור את המסלול הזה, מבוטא בשניות (שדה הערך) וכטקסט. הייצוג הטקסטואלי מותאם לשוק המקומי בהתאם לפרמטר השפה של השאילתה. מידע נוסף זמין במאמר TextValueObject.
`duration_in_traffic`	אופציונלי	TextValueObject	משך הזמן שלוקח לעבור את המסלול הזה, על סמך מצב התנועה הנוכחי וההיסטורי. בפרמטר `traffic_model` של הבקשה מפורטות האפשרויות שאפשר להשתמש בהן כדי לבקש שהערך שיוחזר יהיה אופטימי, פסימי או הערכה משוערת. משך הזמן מבוטא בשניות (השדה value) וכטקסט. הייצוג הטקסטואלי מותאם לשפה המקומית בהתאם לפרמטר השפה של השאילתה. משך הנסיעה בעומס התנועה מוחזר רק אם כל התנאים הבאים מתקיימים: הבקשה כוללת את הפרמטר `departure_time`. מצב התנועה זמין במסלול המבוקש. הפרמטר mode מוגדר ל-driving. מידע נוסף זמין במאמר TextValueObject.
`fare`	אופציונלי	תעריף	אם השדה הזה קיים, הוא מכיל את מחיר הנסיעה הכולל (כלומר, העלות הכוללת של הכרטיסים) במסלול הזה. המאפיין הזה מוחזר רק לבקשות של תחבורה ציבורית ורק לספקי תחבורה ציבורית שבהם מידע על תעריפים זמין. מידע נוסף זמין בקטע תעריף.

מחיר הכרטיס

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

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}

שדה	חובה	סוג	תיאור
`currency`	חובה	מחרוזת	קוד מטבע בתקן ISO 4217 שמציין את המטבע שבו הסכום מבוטא.
`text`	חובה	מחרוזת	הסכום הכולל של מחיר הנסיעה, בפורמט של השפה המבוקשת.
`value`	חובה	number	סכום הנסיעה הכולל, במטבע שצוין.

DistanceMatrixElementStatus

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

TextValueObject

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

שדה	חובה	סוג	תיאור
`text`	חובה	מחרוזת	ערך מחרוזת.
`value`	חובה	number	ערך מספרי.

בקשה ותגובה של Distance Matrix API (מדור קודם) קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מבוא

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

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

מקורות

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

arrival_time

הימנעות

departure_time

language

מצב

אזור

traffic_model

transit_mode

transit_routing_preference

יחידות

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

כתובת URL

curl

כתובת URL

curl

כתובת URL

curl

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

כתובת URL

curl

JSON

XML

מגדירי מיקום

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

כתובת URL

curl

כתובת URL

curl

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

כתובת URL

curl

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

כתובת URL

curl

JSON

XML

DistanceMatrixResponse

destination_addresses

origin_addresses

rows

status

error_message

DistanceMatrixStatus

DistanceMatrixRow

elements

DistanceMatrixElement

status

distance

duration

duration_in_traffic

fare

מחיר הכרטיס

currency

text

value

DistanceMatrixElementStatus

TextValueObject

text

value

בקשה ותגובה של Distance Matrix API (מדור קודם)

`destination_addresses`

`origin_addresses`

`rows`

`status`

`error_message`

`elements`

`status`

`distance`

`duration`

`duration_in_traffic`

`fare`

`currency`

`text`

`value`

`text`

`value`