כאשר Routes API מחשב מסלול, הוא לוקח את ציוני הדרך פרמטרים של הגדרות אישיות שאתם מספקים כקלט. לאחר מכן ה-API מחזיר תשובה שכולל את מסלול ברירת המחדל ונתיב חלופי אחד או יותר.
התגובה יכולה לכלול סוגים שונים של מסלולים ונתונים אחרים, על סמך השדות המבוקשים:
כדי לכלול את המידע הזה בתשובה | צפייה במסמכי התיעוד האלה |
---|---|
המסלול הכי חסכוני בדלק או באנרגיה, על סמך סוג המנוע של הרכב. | הגדרת מסלולים ידידותיים לסביבה |
עד שלושה מסלולים חלופיים | בקשת מסלולים חלופיים |
קו פוליגוני של מסלול שלם, לכל קטע במסלול ולכל שלב של רגל. | בקשה לקווים פוליגוניים של נתיב |
כבישי האגרה המשוערים, תוך התייחסות להנחות במחירי האגרה או כרטיסים שזמינים לנהג או לרכב. | חישוב עמלות האגרה |
תשובות מותאמות לשוק המקומי לפי קודי שפה ויחידת מידה (אימפריאלית או ). | שליחת בקשה לערכים מותאמים לשוק המקומי |
כדי לעצב את הוראות הניווט כמחרוזת טקסט של HTML, צריך להוסיף את הערך HTML_FORMATTED_NAVIGATION_INSTRUCTIONS אל
extraComputations . |
חישובים נוספים |
הרשימה המלאה של אפשרויות הקלט מופיעה במאמר בנושא אפשרויות המסלול הזמינות. את הרצף גוף הבקשה.
התגובה מאפשרת לכם לספק ללקוחות את המידע כדי לבחור את המסלול המתאים לדרישות שלהם.
מידע על מסיכות שדות
כשקוראים לשיטה לחישוב מסלול, צריך לציין שדה מסכה שמגדירה אילו שדות רוצים להחזיר בתשובה. אין ברירת מחדל של השדות שהוחזרו. אם משמיטים את הרשימה הזו, השיטות מחזירות שגיאה.
בדוגמאות שבמסמך הזה אפשר לראות את אובייקט התשובה כולו, בלי לקחת מסכות של שדות. בסביבת ייצור, התשובה שלכם תהיה לכלול רק את השדות שמציינים במפורש במסכת השדות.
מידע נוסף זמין במאמר בחירת המידע שיוחזר.
מידע על הצגת זכויות יוצרים
כשמציגים את התוצאות למשתמשים, צריך לכלול את הצהרת זכויות היוצרים הבאה:
Powered by Google, ©YEAR Google
לדוגמה:
Powered by Google, ©2023 Google
מידע על מסלולים, רגליים ומדרגות
לפני שבודקים את התשובה שחזרה מה-Routes API, צריכה להיות הבנה של הרכיבים שמרכיבים מסלול:
התגובה שלכם עשויה להכיל מידע על כל אחד מרכיבי המסלול הבאים:
מסלול: הנסיעה כולה מנקודת הציון של נקודת המוצא, דרך כל עד נקודת הציון של היעד. מסלול מורכב מנתיב אחד או יותר רגליים.
דרך: הנתיב מנקודת ציון אחת במסלול אל נקודת הציון הבאה ב מסלול. כל רגל מורכבת מצעד נפרד אחד או יותר.
מסלול מכיל רגל נפרדת עבור הנתיב מכל ציון דרך לערוץ הבא. לדוגמה, אם המסלול מכיל ציון דרך יחיד ונקודת ציון ציון דרך של היעד, הנתיב מכיל רגל אחת. בכל פעם להוסיף למסלול אחרי נקודת המוצא והיעד. שנקראת ציון דרך ביניים, ה-API מוסיף שלב נפרד.
ה-API לא מוסיף נקודת רגל לציון דרך ביניים מסוג מעבר. עבור לדוגמה, מסלול שמכיל ציון דרך המוצא, ציון דרך ברמת הביניים, וציון דרך ליעד מכיל רק רגל אחת את המוצא אל היעד, ובמקביל לעבור דרך ציון הדרך. לקבלת מידע נוסף מידע על נקודות ציון מעבר, מגדירים ציון דרך של צדדים שלישיים.
שלב: הוראה אחת לאורך הקטע של המסלול. שלב הוא הפרמטר ביחידה האטומית של המסלול. לדוגמה, שלב יכול לציין "Turn left on Main. רחוב''.
מה יש בתשובה
האובייקט JSON שמייצג את תגובת ה-API מכיל את המאפיינים הבאים ברמה העליונה:
routes
, מערך של רכיבים מסוג ניתוב. מערך ה-routes
מכיל רכיב אחד לכל מסלול שמוחזר על ידי ה-API. המערך יכול להכיל עד חמישה רכיבים: נתיב ברירת המחדל, מסלול ידידותי לסביבה, ועד שלושה מסלולים חלופיים.geocodingResults
, מערך של רכיבים מסוג GeocodingResults. לכל מיקום בבקשה (מקור, יעד או ביניים ציון דרך) שציינתם כמחרוזת כתובת או כ-Plus code, ה-API מבצע חיפוש של מזהה מקום. כל רכיב במערך הזה מכיל את מזהה מקום שתואם למיקום. המיקומים בבקשה שצוינו כ- מזהה מקום או קואורדינטות של קו אורך/רוחב לא כלולים. אם ציינתם את כל המיקומים באמצעות מזהי מקומות או קו רוחב וקו אורך הקואורדינטות, המערך הזה לא קיים.fallbackInfo
, מסוג FallbackInfo. אם ה-API לא מצליח לחשב מסלול מכל מאפייני הקלט, יכול להיות שהוא ישתמש בשיטת חישוב אחרת. כשיש חלופה נמצא בשימוש, שדה זה מכיל מידע מפורט על החלופה תשובה. אחרת, השדה הזה לא מוגדר.
התשובה תיראה כך:
{ // The routes array. "routes": [ { object (Route) } ], // The place ID lookup results. "geocodingResults": [ { object (GeocodedWaypoint) } ], // The fallback property. "fallbackInfo": { object (FallbackInfo) } }
פענוח מערך המסלולים
התגובה מכילה את המערך routes
, שבו כל רכיב מערך הוא מסוג
ניתוב.
כל רכיב מערך מייצג מסלול שלם מהמקור ליעד.
ה-API תמיד מחזיר נתיב אחד לפחות, שנקרא נתיב ברירת המחדל.
אפשר לבקש מסלולים נוספים. אם מבקשים
המסלול הידידותי לסביבה, המערך יכול להכיל שני רכיבים:
מסלול ברירת המחדל והמסלול הידידותי לסביבה. או להגדיר את computeAlternativeRoutes
לערך
true
בבקשה להוסיף עד שלושה מסלולים חלופיים לתשובה.
כל נתיב במערך מזוהה באמצעות המאפיין 'מערך': routeLabels
:
ערך | תיאור |
---|---|
DEFAULT_ROUTE |
מזהה את נתיב ברירת המחדל. |
FUEL_EFFICIENT |
מזהה את המסלול הידידותי לסביבה. |
DEFAULT_ROUTE_ALTERNATE |
מציינת מסלול חלופי. |
מערך legs
מכיל את ההגדרה של כל קטע במסלול. השאר
מאפיינים כמו distanceMeters
, duration
ו-polyline,
מכילים
מידע על המסלול כולו:
{ "routeLabels": [ enum (RouteLabel) ], "legs": [ { object (RouteLeg) } ], "distanceMeters": integer, "duration": string, "routeLabels": [string], "staticDuration": string, "polyline": { object (Polyline) }, "description": string, "warnings": [ string ], "viewport": { object (Viewport) }, "travelAdvisory": { object (RouteTravelAdvisory) } "routeToken": string }
עקב תנאי הנסיעה הנוכחיים וגורמים אחרים, מסלול ברירת המחדל
המסלול הידידותי לסביבה יכול להיות זהה. במקרה הזה, מערך routeLabels
מכילה את שתי התוויות: DEFAULT_ROUTE
וגם FUEL_EFFICIENT
.
{ "routes": [ { "routeLabels": [ "DEFAULT_ROUTE", "FUEL_EFFICIENT" ], … } ] }
הבנת מערך הצעדים
כל route
בתגובה מכיל מערך legs
, שבו כל מערך legs
הרכיב הוא מסוג
RouteLeg.
כל שלב במערך מגדיר את הנתיב מנקודת ציון אחת עד לנקודת הציון הבאה
לאורך המסלול. מסלול תמיד מכיל לפחות רגל אחת.
המאפיין legs
מכיל את ההגדרה של כל שלב לאורך הקטע
מערך steps
. המאפיינים הנותרים, כמו distanceMeters
, duration
,
ו-polyline
מכילים מידע על הרגל.
{ "distanceMeters": integer, "duration": string, "staticDuration": string, "polyline": { object (Polyline) }, "startLocation": { object (Location) }, "endLocation": { object (Location) }, "steps": [ { object (RouteLegStep) } ], "travelAdvisory": { object (RouteLegTravelAdvisory) } }
הסבר על מערך השלבים
כל רגל בתגובה מכילה מערך steps
, שבו כל מערך steps
הרכיב הוא מסוג
RouteLegStep.
שלב תואם להוראה יחידה לאורך הרגל. רגל מכילה תמיד
שלב אחד לפחות.
כל רכיב במערך steps
כולל את navigationInstruction
מאפיין, מסוג
NavigationInstruction,
שמכיל את הוראת השלב. לדוגמה:
"navigationInstruction": { "maneuver": "TURN_LEFT", "instructions": "Turn left toward Frontage Rd" }
יכול להיות שהשדה instructions
מכיל מידע נוסף על השלב. לדוגמה:
"navigationInstruction": { "maneuver": "TURN_SLIGHT_LEFT", "instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days" }
שאר המאפיינים בשלב מתארים פרטים על השלב, כמו
בתור distanceMeters
, duration
, ו-polyline
:
{ "distanceMeters": integer, "staticDuration": string, "polyline": { object (Polyline) }, "startLocation": { object (Location) }, "endLocation": { object (Location) }, "navigationInstruction": { object (NavigationInstruction) } }
ציון השפה של הוראות השלבים
ה-API מחזיר פרטי מסלול בשפה המקומית, בתעתיק הסקריפט קריא על ידי המשתמש, במקרה הצורך, תוך שמירה על בשפת היעד. כל רכיבי הכתובת מוחזרים באותה שפה.
משתמשים בפרמטר
languageCode
של לבקש מ- להגדיר במפורש את שפת המסלול מתוך רשימת ההיתרים שפות. Google מעדכנת את ממשקי ה-API הנתמכים לעיתים קרובות ולכן הרשימה הזו לא מקיפה.אם שם לא זמין בשפה שצוינה, ה-API ישתמש ברכיב ההתאמה הקרובה ביותר.
השפה שצוינה יכולה להשפיע על קבוצת התוצאות ה-API בוחר להחזיר ואת הסדר שבו הן מוחזרות. המקודד הגיאוגרפי מפרש קיצורים באופן שונה בהתאם לשפה, למשל הקיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות אבל לא בשפה אחרת. לדוגמה, utca ו-tér הן מילים נרדפות עבור רחוב בהונגרית.
הסבר על המערך geocoding Results
לכל מיקום בבקשה (מקור, יעד או ביניים
ציון דרך) שצוין כמחרוזת כתובת או כ-Plus code,
ה-API מנסה למצוא את המיקום הרלוונטי ביותר עם מקום מתאים.
ID. כל רכיב
geocodingResults
מערך מכיל את השדה placeID
שמכיל את המיקום כמזהה מקום ושדה type
שמציין את המיקום.
למשל street_address
, premise
או airport
.
המערך geocodingResults
מכיל שלושה שדות:
origin
: אם הוא צוין כמחרוזת כתובת או כ-Plus Code, מזהה המקום של המקור. אחרת, השדה הזה יושמט מהתשובה.destination
: אם הוא צוין כמחרוזת כתובת או כ-Plus Code, מזהה המקום של היעד. אחרת, השדה הזה יושמט תשובה.intermediates
: מערך שמכיל את מזהה המקום של כל ביניים ציוני דרך המוגדרים כמחרוזת כתובת או כ-Plus Code. אם מציינים דרך ביניים באמצעות מזהה מקום או קו רוחב, קואורדינטות של קו האורך, הן מוסרות מהתשובה. משתמשים ב מאפיין אחד (intermediateWaypointRequestIndex
) בתגובה כדי לקבוע איזה ציון דרך בבקשה תואם למזהה המקום את התשובה.
"geocodingResults": { "origin": { "geocoderStatus": {}, "type": [ enum (Type) ], "placeId": string }, "destination": { "geocoderStatus": {}, "type": [ enum (Type) ], "placeId": string }, "intermediates": [ { "geocoderStatus": {}, "intermediateWaypointRequestIndex": integer, "type": [ enum (Type) ], "placeId": string }, { "geocoderStatus": {}, "intermediateWaypointRequestIndex": integer, "type": [ enum (Type) ], "placeId": string } ] }
הסבר על ערכי תשובות שהותאמו לשוק המקומי
ערכי תשובות שהותאמו לשוק המקומי הם שדה תשובה נוסף שמספק מותאם לשוק המקומי לערכי הפרמטרים שהוחזרו. טקסט מותאם לשוק המקומי מסופק עבור משך הנסיעה, המרחק ומערכת היחידה (מידות בשיטה המטרית או האימפריאלית). הבקשה שלך מותאמים לשוק המקומי באמצעות מסכת שדות, ויכולים לציין את השפה מערכת היחידות או להשתמש בערכים שה-API מסיק. פרטים נוספים זמינים במאמר LocalizedValues.
לדוגמה, אם מציינים את קוד השפה עבור גרמנית (de) ואותיות אימפריאליות
יחידות, מקבלים ערך עבור distanceMeters
של 49889.7,
אבל גם מותאם לשוק המקומי שמספק את מדידת המרחק הזאת בגרמנית
יחידות אימפריאליות, כך "31 Meile".
לפניכם דוגמה לנתונים שיכולים להופיע בערכים שהותאמו לשוק המקומי:
{ "localized_values": { "distance": { "text": "31,0 Meile/n" }, "duration": { "text": 38 Minuten}. "static_duration": { "text": 36 Minuten}. } }
אם לא מציינים את השפה או את מערכת היחידות, ה-API מסיק את השפה ויחידות באופן הבא:
- שיטת
ComputeRoutes
מסיקה את המיקום והמרחק מנקודת הציון של המקור. בשביל בקשת ניתוב בארה"ב, ה-API מסיקה שפה אחת (en-US
) ו-IMPERIAL
יחידות. - ברירת המחדל של השיטה
ComputeRouteMatrix
היא en-US שפה ו-METRIC של היחידות.