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

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

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

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

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

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

• מזהה מקום (השדה המועדף)
• קואורדינטות של קווי אורך ורוחב
• מחרוזת כתובת ("שיקגו, אילינוי" או "דרווין, NT, אוסטרליה")
• Plus Code

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

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

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

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

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

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

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

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

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

כדי להגדיר מיקום בציון דרך, צריך לציין את Location (REST) או את Location(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 מקודד באופן פנימי את המחרוזת כדי להמיר אותה לקואורדינטות של קווי אורך ורוחב.

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

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

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

{
  []
}

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

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

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

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

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

ציון מיקום כ-Plus Code

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

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

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

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

• קוד גלובלי מורכב מקוד אזור בן 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, כולל השלמה אוטומטית של מקום, פרטי מקום, API של מסלול ו-Geocoding API. לדוגמה, תוכלו להשתמש ב-Geocoding API כדי להפוך קידוד גיאוגרפי של מיקום שצוין באמצעות קואורדינטות של קווי אורך ורוחב, על מנת לקבוע את ה-Plus Code של המיקום.