מסלול הגעה

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

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

מתקשרים אל method‏ computeRoutes() כדי לבקש מסלול בין שני מיקומים. בדוגמה הבאה מוגדרת בקשה ואז מופעלת הפונקציה computeRoutes() כדי לקבל מסלול. 

  // Import the Routes library.
  const { Route } = await google.maps.importLibrary('routes');

  // Define a computeRoutes request.
  const request = {
    origin: 'Mountain View, CA',
    destination: 'San Francisco, CA',
  };

  // Call the computeRoutes() method to get routes.
  const {routes} = await Route.computeRoutes(request);

בחירת שדות להחזרה

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

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

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

TypeScript

// Define a routes request.
const request = {
  origin: 'Mountain View, CA',
  destination: 'San Francisco, CA',
  travelMode: 'DRIVING',
  fields: ['path'], // Request fields needed to draw polylines.
};
index.ts

JavaScript

// Define a routes request.
const request = {
    origin: 'Mountain View, CA',
    destination: 'San Francisco, CA',
    travelMode: 'DRIVING',
    fields: ['path'], // Request fields needed to draw polylines.
};
index.js

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

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

ב-ComputeRoutesRequest, אפשר לציין מיקום באחת מהדרכים הבאות:

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

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

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

ציון מיקום כאובייקט Place (מומלץ)

כדי לציין מיקום באמצעות מקום, יוצרים מופע חדש של Place. בקטע הקוד הבא מוצגת יצירה של מופעי Place חדשים עבור origin ו-destination, ואז שימוש בהם ב-ComputeRoutesRequest:

TypeScript

// Use Place IDs in a directions request.
const originPlaceInstance = new Place({
  id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
});

const destinationPlaceInstance = new Place({
  id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
});

const requestWithPlaceIds = {
  origin: originPlaceInstance,
  destination: destinationPlaceInstance,
  fields: ['path'], // Request fields needed to draw polylines.
}; 
index.ts

JavaScript

// Use Place IDs in a directions request.
const originPlaceInstance = new Place({
    id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
});
const destinationPlaceInstance = new Place({
    id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
});
const requestWithPlaceIds = {
    origin: originPlaceInstance,
    destination: destinationPlaceInstance,
    fields: ['path'], // Request fields needed to draw polylines.
};
index.js

קואורדינטות של קו הרוחב/קו האורך

כדי לציין מיקום באמצעות קואורדינטות של קו רוחב/אורך, יוצרים מופע חדש של google.maps.LatLngLiteral, google.maps.LatLngAltitude או google.maps.LatLngAltitudeLiteral. בקטע הקוד הבא מוצגת יצירה של מופעי google.maps.LatLngLiteral חדשים עבור origin ו-destination, ולאחר מכן שימוש בהם ב-computeRoutesRequest:

TypeScript

// Use lat/lng in a directions request.
// Mountain View, CA
const originLatLng = {lat: 37.422000, lng: -122.084058};
// San Francisco, CA
const destinationLatLng = {lat: 37.774929, lng: -122.419415};

// Define a computeRoutes request.
const requestWithLatLngs = {
  origin: originLatLng,
  destination: destinationLatLng,
  fields: ['path'],
};
index.ts

JavaScript

// Use lat/lng in a directions request.
// Mountain View, CA
const originLatLng = { lat: 37.422000, lng: -122.084058 };
// San Francisco, CA
const destinationLatLng = { lat: 37.774929, lng: -122.419415 };
// Define a computeRoutes request.
const requestWithLatLngs = {
    origin: originLatLng,
    destination: destinationLatLng,
    fields: ['path'],
};
index.js

מחרוזת כתובת

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

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

בקטע הקוד הבא מוצג תהליך יצירת ComputeRoutesRequest עם מחרוזת כתובת בשביל origin ו-destination:

TypeScript

// Use address strings in a directions request.
const requestWithAddressStrings = {
  origin: '1600 Amphitheatre Parkway, Mountain View, CA',
  destination: '345 Spear Street, San Francisco, CA',
  fields: ['path'],
};
index.ts

JavaScript

// Use address strings in a directions request.
const requestWithAddressStrings = {
    origin: '1600 Amphitheatre Parkway, Mountain View, CA',
    destination: '345 Spear Street, San Francisco, CA',
    fields: ['path'],
};
index.js

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

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

// Define a request with an incomplete address string.
const request = {
  origin: 'Toledo',
  destination: 'Madrid',
};

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

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

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

const request = {
  origin: 'Toledo',
  destination: 'Madrid',
  region: 'es', // Specify the region code for Spain.
};

Plus Code

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

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

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

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

  • קוד גלובלי מורכב מקידומת אזור בת 4 תווים ומקוד מקומי בן 6 תווים או יותר. לדוגמה, לכתובת "1600 Amphitheatre Parkway, Mountain View, CA", הקוד הגלובלי הוא "849V" והקוד המקומי הוא "CWC8+R9". לאחר מכן משתמשים ב-OLC המלא בן 10 התווים כדי לציין את ערך המיקום כ-"849VCWC8+R9".
  • קוד מורכב מורכב מקוד מקומי באורך 6 תווים או יותר, בשילוב עם מיקום מפורש. לדוגמה, הכתובת "450 Serra Mall, Stanford, CA 94305, USA" כוללת קוד מקומי של "CRHJ+C3". אם הכתובת מורכבת, משלבים את הקוד המקומי עם העיר, המדינה, המיקוד והמדינה של הכתובת בצורה "CRHJ+C3 סטנפורד, קליפורניה 94305, ארה"ב".

בקטע הקוד הבא מוצג חישוב של מסלול על ידי ציון נקודת ביניים לנקודת המוצא וליעד של המסלול באמצעות Plus Codes:

TypeScript

// Use Plus Codes in a directions request.
const requestWithPlusCodes = {
  origin: '849VCWC8+R9', // Mountain View, CA
  destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
  fields: ['path'],
};
index.ts

JavaScript

// Use Plus Codes in a directions request.
const requestWithPlusCodes = {
    origin: '849VCWC8+R9', // Mountain View, CA
    destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
    fields: ['path'],
};
index.js