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

כש-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 כוללת מסלול חלופי.

המערך 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 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.