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

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

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

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

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

מידע על מסכות שדות

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

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

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

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

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

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:

המערך 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"
      ],
     …
    }
  ]
}

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

כל 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) ויחידות אימפריאליות, מקבלים ערך של 49889.7 בשדה distanceMeters, אבל גם טקסט מותאם לשוק המקומי שמספק את מדידת המרחק הזו בגרמנית וביחידות אימפריאליות, כלומר "‎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.