בדיקת התגובה של המסלול

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

התשובה יכולה לכלול סוגים שונים של מסלולים ונתונים אחרים, בהתאם לשדות שביקשת:

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

הרשימה המלאה של אפשרויות הקלט מפורטת בקטע אפשרויות זמינות למסלול ובגוף הבקשה.

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

מידע על אנונימיזציה של שדות

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

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

מידע נוסף זמין במאמר בחירת המידע שיוחזר.

מידע על הצגת זכויות יוצרים

כשמציגים את התוצאות למשתמשים, צריך לכלול את הצהרת זכויות היוצרים הבאה:

Powered by Google, ©YEAR Google

לדוגמה:

Powered by Google, ©2023 Google

מידע על מסלולים, קטעים ושלבים

לפני שבודקים את התשובה שמוחזרת על ידי Routes API, כדאי להבין את הרכיבים שמרכיבים מסלול:

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

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

• שלב: הנתיב מנקודת ציון אחת בנתיב לנקודת הציון הבאה בנתיב. כל שלב מורכב משלבים נפרדים אחד או יותר.

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

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

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

מה נכלל בתשובה

אובייקט ה-JSON שמייצג את תגובת ה-API מכיל את המאפיינים הבאים ברמה העליונה:

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

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

כל מסלול במערך מזוהה באמצעות מאפיין המערך routeLabels:

ערך	תיאור
DEFAULT_ROUTE	מזהה את מסלול ברירת המחדל.
FUEL_EFFICIENT	זיהוי המסלול הידידותי לסביבה.
DEFAULT_ROUTE_ALTERNATE	I מציין מסלול חלופי.

המערך 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 בוחר להחזיר ועל הסדר שבו הן מוחזרות. המערכת למיפוי גיאוגרפי מפענחת קיצורים באופן שונה בהתאם לשפה, למשל קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת. לדוגמה, utca ו-tér הם שמות נרדפים לרחוב בהונגרית.

הסבר על המערך geocodingResults

לכל מיקום בבקשה (מקור, יעד או נקודת ציון ביניים) שצוין כמחרוזת כתובת או כPlus Code, ה-API מנסה למצוא את המיקום הרלוונטי ביותר שיש לו מזהה מקום תואם. כל רכיב במערך geocodingResults מכיל את השדה placeID שמכיל את המיקום כמזהה מקום, ואת השדה type שמציין את סוג המיקום, למשל street_address, ‏ premise או airport.

המערך geocodingResults מכיל שלושה שדות:

• origin: אם הוא צוין כמחרוזת של כתובת או כקוד Plus, מזהה המקום של המקור. אחרת, השדה הזה לא ייכלל בתגובה.

• 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}.
  }
}

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

• השיטה ComputeRoutes מסיקה את המיקום ואת יחידות המרחק מנקודת הציון של המקור. לכן, בבקשת ניתוב בארה"ב, ה-API מסיק את השפה en-US והיחידות IMPERIAL.
• שפת ברירת המחדל של השיטה ComputeRouteMatrix היא 'en-US' ויחידות ברירת המחדל הן METRIC.