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

כשממשק 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. לכל מיקום בבקשה (מקור, יעד או נקודת ביניים) שציינתם כמחרוזת כתובת או כקוד פלוס, ה-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"
      ],
     …
    }
  ]
}

הסבר על מערך הרגליים

כל 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' ולמערכת יחידות מטרית.