הצטרפו אלינו לאירוע הבא של Google Maps Platform Developer Community Day בסן פרנסיסקו בדצמבר. להגשת בקשה להשתתפות.

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

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

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

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

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

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

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

מזהה מקום (מועדף)
קואורדינטות של קו הרוחב/קו האורך
מחרוזת כתובת ("Chicago, IL" או "Darwin, NT, Australia")
אסימון של נקודת ניווט
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"). המרת כתובות לקואורדינטות (geocoding) היא תהליך של המרת מחרוזת כתובת לקואורדינטות של קווי רוחב ואורך (למשל, קו רוחב 37.423021 וקו אורך ‎-122.083739).

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

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

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

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

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

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

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

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

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

{
  []
}

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

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

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

התשובה מכילה עכשיו את המסלול שחושב מטולדו, ספרד למדריד, ספרד:

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

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

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

כדי לקבל טוקן של נקודת ניווט, צריך להפעיל את השיטה Destinations של Geocoding API.

כדי לציין אסימון של נקודת ניווט:

מקבלים navigationPointToken מה-method‏ SearchDestinations של Geocoding API. מידע נוסף זמין במאמרי העזרה של Geocoding API.
יוצרים נקודת דרך באמצעות העברת navigationPointToken.

בדוגמה הבאה, המאפיין navigation_point_token משמש להעברת טוקן של נקודת ניווט גם ל-origin וגם ל-destination:

{
  "origin":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_ORIGIN"
  },
  "destination":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_DESTINATION"
  },
  ...
}

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

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

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

‫Google פיתחה את Plus Codes כדי שכולם יוכלו ליהנות מהיתרונות של כתובות. ‫Plus Code הוא הפניה מקודדת למיקום, שנגזרת מקואורדינטות של קו רוחב/קו אורך ומייצגת אזור: 1/8,000 של מעלה על 1/8,000 של מעלה (בערך 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 Codes:
```
{
  "origin":{
    "address": "849VCWC8+R9"
  },
  "destination":{
    "address": "CRHJ+C3 Stanford, CA 94305, USA"
  },
  "travelMode": "DRIVE"
}
```

יש תמיכה ב-Plus Codes בממשקי ה-API של Google Maps Platform, כולל השלמה אוטומטית (חדש), Place Details (חדש) ו-Geocoding API. לדוגמה, אתם יכולים להשתמש ב-Geocoding API כדי להמיר קואורדינטות של קווי אורך ורוחב לכתובת (reverse geocoding), וכך לקבוע את ה-Plus Code של המיקום.