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

מפתחים באזור הכלכלי האירופי (EEA)

כש-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. לכל מיקום בבקשה (נקודת מוצא, יעד או נקודת ביניים) שצוין כמחרוזת כתובת או כקוד OLC, ה-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 Indicates an alternative route.

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

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