查看路由响应

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

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

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

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

您可以根据响应，为客户提供根据其需求选择合适路线所需的信息。

关于字段掩码

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

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

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

关于显示版权信息

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

Powered by Google, ©YEAR Google

例如：

Powered by Google, ©2023 Google

路线、路段和步骤简介

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

您的响应可能包含以下各个路线组成部分的相关信息：

• 路线：从起始航点经过所有中间航点到达目的地航点的整个行程。路线由一个或多个路程组成。

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

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

  该 API 不会为穿行中间航点添加航段。例如，包含出发点航点、穿行中继航点和目的地航点的路线仅包含从出发点到目的地的一程，且会经过中继航点。如需详细了解透视航点，请参阅定义透视航点。

• 步骤：路线路段中的单个指示。步是路线的最小单位。例如，某个步骤可以指示“在 Main Street 上左转”。

响应中的内容

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

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

• 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 数组，其中每个数组元素的类型均为 Route。数组中的每个元素都代表从起点到目的地的整个路线。API 始终会返回至少一条路线，称为默认路线。

您可以申请其他路线。如果您请求环保路线，则数组可以包含两个元素：默认路线和环保路线。或者，在请求中将 computeAlternativeRoutes 设置为 true，以便向响应中添加最多 3 条备选路线。

数组中的每个路线都通过 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。步骤对应于沿着路径的单个指令。行程始终包含至少 1 个步骤。

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 的地点。geocodingResults 数组的每个元素都包含一个 placeID 字段，其中包含作为地点 ID 的位置信息，以及一个 type 字段，用于指定位置类型，例如 street_address、premise 或 airport。

geocodingResults 数组包含三个字段：

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

• destination：如果目标位置是作为地址字符串或 Plus Code 指定的，则为目标位置的地点 ID。否则，系统会从响应中省略此字段。

• intermediates：一个数组，其中包含指定为地址字符串或 Plus Code 的任何中间航点的地点 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 单位。
• ComputeRouteMatrix 方法默认采用“英语（美国）”语言和公制单位。