המוצר הזה נמצא בסטטוס מדור קודם. החל מאוקטובר 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 צריכים להיות בפורמט של קוד גלובלי או קוד מורכב. צריך להשתמש בפורמט של קודי פלוס שמוצג כאן (סימני הפלוס מקודדים ל-‎ %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. אם מציינים ערך של a 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 צריכה להיות השעה הנוכחית או שעה בעתיד. התאריך לא יכול להיות בעבר.
הערה: אם לא מציינים שעת יציאה, בחירת המסלול והמשך שלו מבוססים על רשת הכבישים ועל מצב התנועה הממוצע שלא תלוי בשעה. התוצאות של בקשה מסוימת עשויות להשתנות לאורך זמן בגלל שינויים ברשת הכבישים, עדכונים במצב התנועה הממוצע והאופי המבוזר של השירות. התוצאות עשויות להיות שונות גם בין מסלולים כמעט זהים בכל זמן או תדירות.

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

השפה שבה יוחזרו התוצאות.
- כאן אפשר לעיין ברשימת השפות הנתמכות. ‫Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא מלאה.
- אם לא מספקים את language, ה-API מנסה להשתמש בשפה המועדפת שצוינה בכותרת Accept-Language.
- ה-API עושה כמיטב יכולתו כדי לספק כתובת רחוב שגם המשתמש וגם המקומיים יוכלו לקרוא. כדי להשיג את המטרה הזו, היא מחזירה כתובות רחוב בשפה המקומית, בתעתיק לכתב שניתן לקריאה על ידי המשתמש אם יש צורך בכך, בהתאם לשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מתוך הרכיב הראשון.
- אם השם לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הכי קרובה.
- לשפה המועדפת יש השפעה קטנה על קבוצת התוצאות שממשק ה-API בוחר להחזיר, ועל הסדר שבו הן מוחזרות. הגיאוקודר מפרש קיצורים בצורה שונה בהתאם לשפה, למשל קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת. לדוגמה, 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'

בדוגמה הזו נעשה שימוש ב-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 בתגובה של Distance Matrix):

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

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

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

כתובת 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

שדה	חובה	סוג	תיאור
`destination_addresses`	חובה	Array<string>	מערך של כתובות שמוחזר על ידי ה-API מהבקשה המקורית. כמו ב-`origin_addresses`, אלה מותאמים לשוק המקומי אם זה מתאים. התוכן הזה נועד לקריאה כמו שהוא. אל תנתחו את הכתובות המעוצבות באופן פרוגרמטי.
`origin_addresses`	חובה	Array<string>	מערך של כתובות שמוחזר על ידי ה-API מהבקשה המקורית. הפורמט שלהם נקבע על ידי הגיאוקודר והם מותאמים לשפה שמועברת עם הבקשה באמצעות פרמטר השפה. התוכן הזה נועד לקריאה כמו שהוא. אל תנתחו את הכתובות המעוצבות באופן אוטומטי.
`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 מציין שהשירות דחה את השימוש בשירות Distance Matrix של האפליקציה.
השגיאה 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` מפורטות האפשרויות שבהן אפשר להשתמש כדי לבקש שהערך שיוחזר יהיה אופטימי, פסימי או הערכה משוערת. המשך מוצג בשניות (בשדה הערך) ובטקסט. הייצוג הטקסטואלי מותאם לשוק המקומי בהתאם לפרמטר השפה של השאילתה. הערך של משך הזמן בתנועה מוחזר רק אם מתקיימים כל התנאים הבאים: הבקשה כוללת את הפרמטר `departure_time`. מצב התנועה זמין במסלול המבוקש. פרמטר המצב מוגדר לנהיגה. מידע נוסף זמין במאמר בנושא TextValueObject.
`fare`	אופציונלי	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

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

כתובת 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`