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

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

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

כדי לכלול את המידע הזה בתשובה	צפייה במסמכי התיעוד האלה
המסלול הכי חסכוני בדלק או באנרגיה, על סמך סוג המנוע של הרכב.	הגדרת מסלולים ידידותיים לסביבה
עד שלושה מסלולים חלופיים	בקשת מסלולים חלופיים
הקו הפוליגוני של מסלול שלם, לכל רגל במסלול ולכל שלב במסלול.	בקשה לקווים פוליגוניים של נתיב
אגרות האגרה המשוערות, תוך התייחסות להנחות במחירי האגרה או לכרטיסים שזמינים לנהג או לרכב.	חישוב עמלות האגרה
תשובות מותאמות לשוק המקומי לפי קודי שפה ויחידת מידה (אימפריאלית או מטרית).	שליחת בקשה לערכים מותאמים לשוק המקומי
כדי לעצב את הוראות הניווט כמחרוזת טקסט של HTML, צריך להוסיף את הערך HTML_FORMATTED_NAVIGATION_INSTRUCTIONS אל extraComputations.	חישובים נוספים

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

באמצעות התשובה תוכלו לספק ללקוחות את המידע הנחוץ כדי לבחור את המסלול המתאים לדרישות שלהם.

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

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

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

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

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

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

Powered by Google, ©YEAR Google

למשל:

Powered by Google, ©2023 Google

מידע על מסלולים, רגליים ומדרגות

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

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

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

• דרך: הנתיב מנקודת ציון אחת במסלול אל נקודת הציון הבאה במסלול. כל רגל מורכבת מצעד נפרד אחד או יותר.

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

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

• שלב: הוראה אחת לאורך הקטע של המסלול. שלב הוא היחידה האטומית ביותר של מסלול. לדוגמה, שלב יכול לציין "Turn left on Main Street".

מה יש בתשובה

אובייקט 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 הן מילים נרדפות של רחוב בהונגרית.

הסבר על המערך geocoding Results

לכל מיקום בבקשה (מקור, יעד או נקודת ציון ביניים) שצוין כמחרוזת כתובת או כקוד Plus, ה-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.
• ברירת המחדל של ה-method ComputeRouteMatrix היא השפה 'en-US' ויחידות METRIC.