Routes API 目前处于预览版阶段(正式发布前)。正式发布前产品和功能的支持可能有限,并且对正式发布前产品和功能的变更可能与其他正式发布前版本不兼容。正式发布预备产品受 Google Maps Platform 服务专用条款的约束。如需了解详情,请参阅发布阶段说明

配置质量与延迟时间

当您发出请求时,可能必须决定是最好返回最准确的结果,还是尽快返回结果。您可以使用 Routes API 提供的选项来控制响应数据的质量与响应的延迟时间。

配置流量数据级别

借助 Routes API 提供的 RoutingPreference (REST) 和 RoutingPreference (gRPC),您可以为计算路由指定路由偏好设置。这些偏好设置在将流量条件纳入路由计算范围方面有所不同。每个路由偏好设置产生的结果在路由质量、预计 ETA 和响应延迟时间方面各不相同。

路况信息用于描述流量的速率。例如:

  • 当没有拥堵时,流量条件会被视为正常,流量按常规无阻速度流动。
  • 即将进入高峰期时,流量密度会增加,这会导致流量减慢,产生适中的路况信息。
  • 在导视广告的缓冲流量中,流速会逐渐提升到暂停状态,从而导致交通拥堵。

流量不知道

设置 TRAFFIC_UNAWARE 路由偏好设置后,系统在计算路线时不考虑当前路况。此路由偏好设置可提供最低的响应延迟时间(返回响应的速度最快)。

默认设置是 TRAFFIC_UNAWARE

在响应中:

  • ETA 包含在 duration 响应属性中。

  • durationstaticDuration 响应属性包含相同的值。

如果您希望响应返回最快,并且大致的路由详情足够好,请使用此路由偏好设置。

路况感知

设置 TRAFFIC_AWARE 路由偏好设置后,系统在计算路由时会考虑当前路况。因此,路线和路线详情可以更准确地反映现实情况。由于数据质量的增加会牺牲响应延迟时间,因此应用性能优化以减少大部分延迟时间。

在响应中:

  • 将实时流量考虑在内的 ETA 包含在 duration 响应属性中。

  • staticDuration 响应属性包含该路线的行程时长,而不考虑路况条件。

当您想要比 TRAFFIC_UNAWARE 更精确的路由详情,而且不介意是否返回延迟时间适度增加时,可以使用此路由偏好设置。

路况感知最优

设置 TRAFFIC_AWARE_OPTIMAL 路由偏好设置后,路由会按照当前路况条件进行计算,但不会应用任何性能优化。在此模式下,服务器会对道路网络执行更详尽的搜索,以查找最佳路线。

TRAFFIC_AWARE_OPTIMAL 路线偏好设置等同于 maps.google.com 和 Google 地图移动应用使用的模式。

将此选项与计算路由矩阵一起使用时,请求中的元素数量(源数 × 目标数)不能超过 100。如需详细了解计算路由矩阵限制,请参阅计算路由矩阵

在响应中:

  • 将实时流量考虑在内的 ETA 包含在 duration 响应属性中。

  • staticDuration 响应属性包含该路线的行程时长,而不考虑路况条件。

此路由偏好设置可提供最高的响应延迟时间(即响应返回延迟时间最长)。如果您希望获得最高质量的结果而不考虑响应所用的时间,请使用此路由偏好设置。

设置出发时间的影响

您可以选择使用 departureTime 属性设置行程所需的出发时间。如果未设置 departureTime 属性,则默认为您发出请求的时间。

  • 对于 TRAFFIC_UNAWARE,您无法设置 departureTime,因为系统会根据道路网络和与时间无关的平均路况信息来选择路线和时长。

  • 对于将实时路况考虑在内的 TRAFFIC_AWARETRAFFIC_AWARE_OPTIMAL,实时流量越接近 departureTime 现在越重要。您设置得越远,未来的时间就越长,就会考虑历史路况。

设置转送偏好设置的示例

以下 JSON 代码演示了如何在请求消息实体正文中设置路由偏好设置。

{
  "origin":{
    "location":{
      "latLng":{
        "latitude":37.419734,
        "longitude":-122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude":37.417670,
        "longitude":-122.079595
      }
    }
  },
  "travelMode":"DRIVE",
  "routingPreference":"TRAFFIC_AWARE_OPTIMAL"
}

配置多段线质量

借助 Routes API,您可以请求沿着路况感知型多段线传输路况信息。如需了解详情,请参阅在多段线上请求路况信息

多段线的质量可以用以下字词描述:

  • 多段线的点数

    点越多,多段线越平滑(尤其是在曲线中)。

  • 点的浮点精度

    点以纬度和经度值的形式表示,以单精度浮点格式表示。这种方式非常适合较小的值(可以精确表示),但精度会随着浮点舍入误差而提高。

computeRoutes 方法 (REST) 和 ComputeRoutes 方法 (gRPC) 支持控制多段线质量的 polylineQuality 请求选项。

设置多段线质量的示例

polylineQuality,用于将多段线的质量指定为 HIGH_QUALITYOVERVIEW(默认)。使用 OVERVIEW 时,多段线使用少量点组成,请求延迟时间比 HIGH_QUALITY 短。

例如,在请求正文中:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "polylineQuality": "HIGH_QUALITY",
  "polylineEncoding": "ENCODED_POLYLINE", 
  "departureTime": "2023-10-15T15:01:23.045123456Z",
  ...
}