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

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

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

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

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

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

• מזהה מקום (מועדף)
• קואורדינטות של קו אורך/רוחב
• מחרוזת כתובת ("שיקגו, אילינוי" או "דרווין, NT, אוסטרליה")
• 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 יפעיל חיפוש כדי להבדיל בין כתובות דומות. לדוגמה, '1st Street' יכול להיות ערך מלא או ערך חלקי ל-'1st Street NE' או ל-'1st St SE'. התוצאה הזו עשויה להיות שונה מהתוצאה שמוחזרת על ידי Geocoding API. השימוש במזהי מקומות יעזור לכם למנוע פרשנויות שגויות.

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

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

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

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

{
  []
}

אפשר להגדיר את ה-API כך שיחזיר תוצאות מוטות לאזור מסוים על ידי הכללת הפרמטר regionCode. הפרמטר הזה מציין את קוד האזור בתור ערך בן שני תווים של ccTLD ('דומיין ברמה עליונה'). רוב הקודים של TLD ברמת המדינה זהים לקודי ISO 3166-1, מלבד כמה יוצאים מן הכלל. לדוגמה, הדומיין ccTLD של בריטניה הוא '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 כדי לספק את היתרון של כתובות לכולם. Plus Code הוא הפניה מקודדת של מיקום, שנגזרת מקואורדינטות של קו רוחב/קו אורך, שמייצגת שטח: 1/8,000 מעלות במעלה 1/8,000 מעלה (בערך 14m x 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 Codes נתמכים בממשקי ה-API של הפלטפורמה של מפות Google, כולל השלמה אוטומטית של מקום, פרטי מקום, Directions API ו-Geocoding API. לדוגמה, אפשר להשתמש ב-Geocoding API כדי להפוך את הקידוד הגיאוגרפי של מיקום שצוין באמצעות קואורדינטות של קו רוחב או קו אורך, וכך לזהות את ה-Plus Code של המיקום.