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

כש-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, ה-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, ה-API מנסה למצוא את המיקום הרלוונטי ביותר שיש לו מזהה מקום תואם. כל רכיב במערך geocodingResults מכיל את השדה placeID שמכיל את המיקום כמזהה מקום ושדה type שמציין את סוג המיקום, למשל street_address, premise או airport.

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

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

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

• intermediates: מערך שמכיל את מזהה המקום של כל נקודות הדרך ברמת הביניים שצוינו כמחרוזת של כתובת או כקוד Plus. אם תציינו נקודת ציון ברמת הביניים באמצעות מזהה מקום או קואורדינטות של קווי אורך ורוחב, היא לא תיכלל בתשובה. השתמשו במאפיין 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.