ציון מיקומים למסלול

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

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

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

ציון מיקומים במסלול

כדי לייצג מיקום, יוצרים אובייקט Waypoint (‏REST) או Waypoint (‏gRPC). בהגדרה של נקודת הציון אפשר לציין מיקום באחת מהדרכים הבאות:

• מזהה מקום (מועדף)
• קואורדינטות של קו אורך/רוחב
• מחרוזת כתובת ('תל אביב, תל אביב' או 'תל אביב, תל אביב, ישראל')
• Plus Code

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

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

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

ציון מיקום כמזהה מקום

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

אחזור מזהי מקומות מ-Geocoding API ומ-Places API (כולל השלמה אוטומטית של מקומות). מידע נוסף על מזהי מקומות זמין במאמר סקירה כללית על מזהי מקומות.

בדוגמה הבאה נעשה שימוש במאפיין placeId כדי להעביר מזהה מקום גם ל-origin וגם ל-destination:

{
  "origin":{
    "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o"
  },
  "destination":{
    "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU"
  },
  ...
}

ציון מיקום כקואורדינטות של קו אורך וקו רוחב

כדי להגדיר מיקום בנקודת ציון, מציינים את המיקום (REST) או את המיקום(gRPC) באמצעות קואורדינטות של קו רוחב/אורך.

לדוגמה, אפשר לציין נקודת ציון במסלול origin ו-destination באמצעות הקואורדינטות latitude ו-longitude:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
...
}

ציון מיקום כמחרוזת כתובת

מחרוזות כתובות הן כתובות מילוליות שמיוצגות על ידי מחרוזת (למשל ‎1600 Amphitheatre Parkway, Mountain View, CA). גיאוקוד הוא תהליך המרה של מחרוזת כתובת לקואורדינטות של קווי רוחב ואורך (כמו קו רוחב 37.423021 וקו אורך -122.083739).

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

לדוגמה, כדי לחשב מסלול, מציינים נקודת ציון למסלול origin ו-destination באמצעות מחרוזות כתובות:

{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "450 Serra Mall, Stanford, CA 94305, USA"
  },
  ...
}

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

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

הגדרת האזור של הכתובת

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

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE"
}

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

{
  []
}

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

בקשה לקבלת מסלול מ-Toledo ל-Madrid שכוללת את הפרמטר regionCode מחזירה תוצאות מתאימות, כי מערכת החיפוש מפרשת את Toledo כעיר בספרד:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE",
  "regionCode": "es"
}

התשובה מכילה עכשיו את המסלול שחושב מטוֹלֶדוֹ (ספרד) למדריד (ספרד):

{
  "routes": [
    {
      "distanceMeters": 75330,
      "duration": "4137s",
      ...
    }
  ]
}

ציון מיקום באמצעות Plus Code

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

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

Google פיתחה את Plus Codes כדי לתת לכולם ולכל דבר את היתרונות של כתובות. קוד OLC הוא הפניה מקודדת למיקום, שמבוססת על קואורדינטות קו הרוחב/קו האורך, שמייצגת אזור: 1/8000 של מעלה על 1/8000 של מעלה (כ-14 מ' על 14 מ' בקווי הרוחב) או קטן יותר. אפשר להשתמש ב-Plus Codes כתחליף לכתובות רחוב במקומות שבהם הן לא קיימות, או במקומות שבהם אין מספרים לבניינים או שמות לרחובות.

הפורמט של Plus Codes חייב להיות קוד גלובלי או קוד מורכב:

• קוד גלובלי מורכב מקידומת אזור בת 4 תווים ומקוד מקומי באורך 6 תווים או יותר.

  לדוגמה, לכתובת ‎1600 Amphitheatre Parkway, Mountain View, CA, הקוד הגלובלי הוא ‎849V והקוד המקומי הוא ‎CWC8+R9. לאחר מכן משתמשים ב-Plus Code המלא בן 10 התווים כדי לציין את ערך המיקום בתור '849VCWC8+R9'.

• קוד מורכב מורכב מקוד מקומי בן 6 תווים או יותר בשילוב עם מיקום מפורש.

  לדוגמה, הכתובת ‎450 Serra Mall, Stanford, CA 94305, USA‎ כוללת את הקוד המקומי ‎CRHJ+C3‎. בכתובת מורכבת, משלבים את הקוד המקומי עם החלק של העיר, המדינה, המיקוד והמדינה בכתובת, בפורמט "CRHJ+C3 Stanford, CA 94305, USA".

  לדוגמה, כדי לחשב מסלול, מציינים נקודת ציון למסלול origin ו-destination באמצעות קודי Plus Code:

  {
    "origin":{
      "address": "849VCWC8+R9"
    },
    "destination":{
      "address": "CRHJ+C3 Stanford, CA 94305, USA"
    },
    "travelMode": "DRIVE"
  }

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