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