查看路由响应

欧洲经济区 (EEA) 开发者

Routes API 计算路线时，会将您提供的航点和配置参数作为输入。然后，该 API 会返回一个响应，其中包含默认路线以及一条或多条备选路线。

您的响应可以包含不同类型的路线和其他数据，具体取决于您请求的字段：

如需在响应中添加此内容 请参阅此文档
根据车辆的发动机类型，提供最省油或最节能的路线。 配置环保路线
最多三条备选路线 请求备选路线
整条路线、路线的每段行程以及行程的每个步骤对应的折线。 请求路线折线
预估通行费，并考虑驾驶员或车辆可享受的任何通行费折扣 或通行证。 计算通行费
按语言代码和计量单位（英制或 公制）提供本地化响应。 请求本地化值
如需将导航说明格式化为 HTML 文本字符串，请将 HTML_FORMATTED_NAVIGATION_INSTRUCTIONS 添加到 extraComputations。 额外计算

如需查看输入选项的完整列表，请参阅可用路线选项 和 请求正文。

借助响应，您可以为客户提供必要的信息，以便他们根据自己的需求选择合适的路线。

关于字段掩码

调用方法来计算路线时，您必须指定一个字段掩码，用于定义您希望在响应中返回哪些字段。没有返回字段的默认列表。如果您省略此列表，这些方法会返回错误。

本文档中的示例展示了整个响应对象，而未考虑字段掩码。在生产环境中，您的响应只会包含您在字段掩码中明确指定的字段。

如需了解详情，请参阅选择要返回的信息。

关于显示版权信息

向用户显示结果时，您必须添加以下版权声明：

Powered by Google, ©YEAR Google

例如：

Powered by Google, ©2023 Google

关于路线、行程和步骤

在查看 Routes API 返回的响应之前，您应该了解构成路线的组件：

路线、路段和步数。

您的响应可能包含有关这些路线组件的信息：

  • 路线：从出发地航点到目的地航点（途经任何 中间航点）的整个行程。一条路线由一段或多段行程组成。

  • 行程：从路线中的一个航点到路线中的下一个航点 的路径。每段行程由一个或多个离散步骤组成。

    一条路线包含从每个航点到下一个航点的单独行程。 例如，如果路线包含一个出发地航点和一个目的地航点，则该路线包含一段行程。对于您在出发地和目的地之后添加到路线中的每个 额外航点（ 称为中间航点），API 都会添加一段单独的行程。

    对于直通中间航点， API 不会添加行程。例如，一条路线包含一个出发地航点、一个直通中间航点和一个目的地航点，则该路线仅包含一段从出发地到目的地的行程，途经该航点。如需详细了解直通航点，请参阅 定义直通航点。

  • 步骤：路线行程中的单条说明。步骤是路线的最小单位。例如，一个步骤可以表示“在主街左转”。

响应内容

表示 API 响应的 JSON 对象 包含以下顶级属性：

  • routes，类型为 Route的元素数组。 routes 数组包含 API 返回的每条路线对应的一个元素。该数组最多可以包含五个元素：默认路线、环保路线以及最多三条备选路线。

  • geocodingResults，类型为 GeocodingResults的元素数组。 对于您在请求中指定为地址字符串或Plus 代码的每个位置（出发地、目的地或中间 航点）， API 都会执行地点 ID 查找。此数组的每个元素都包含与某个位置对应的地点 ID。请求中指定为地点 ID 或纬度/经度坐标 的位置不包含在内。 如果您使用地点 ID 或纬度和经度坐标指定了所有位置，则不会提供此数组。

  • fallbackInfo，类型为 FallbackInfo。 如果 API 无法根据所有输入属性计算路线，则可能会回退到使用其他计算方式。使用回退模式时，此字段包含有关回退响应的详细信息。否则，此字段将处于未设置状态。

响应采用以下形式：

{
  // The routes array.
  "routes": [
    {
      object (Route)
    }
  ],
  // The place ID lookup results.
  "geocodingResults": [
    {
      object (GeocodedWaypoint)
    }
  ],
  // The fallback property.
  "fallbackInfo": {
    object (FallbackInfo)
  }
}

解读 routes 数组

响应包含 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"
      ],
     …
    }
  ]
}

了解 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 数组，其中每个 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 都会尝试查找具有相应地点 ID 的最相关位置。数组的每个元素都包含 placeID 字段（其中包含以地点 ID 形式表示的位置）以及 type 字段（用于指定位置类型，例如 street_address、premise 或 airport）。geocodingResults

geocodingResults 数组包含三个字段：

  • origin：如果出发地指定为地址字符串或 Plus 代码，则为出发地的地点 ID。否则，响应中会省略此字段。

  • destination：如果目的地指定为地址字符串或 Plus 代码，则为目的地的地点 ID。否则，响应中会省略此字段。

  • intermediates：一个数组，其中包含指定为地址字符串或 Plus 代码的任何中间航点的地点 ID。如果您使用地点 ID 或纬度和经度坐标指定中间航点，则响应中会省略该航点。使用响应中的 intermediateWaypointRequestIndex 属性来确定请求中的哪个中间航点对应于响应中的地点 ID。

"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 单位。
  • The ComputeRouteMatrix 方法默认使用“en-US”语言 和 METRIC 单位。