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

请求关于多段线的路况信息

借助 Routes API,您可以请求沿着路况感知型多段线显示路况信息。路况条件用响应多段线的给定时间间隔适用的速度类别(NORMALSLOWTRAFFIC_JAM)表示。这些间隔由其起点(含)和结束(不含)多段线的索引定义。

有关多段线的更多信息,请参阅:

返回多段线

多段线由多段线 (REST) 或多段线 (gRPC) 对象表示。在响应中,您可以在路线和路程级别返回一个多段线。

使用响应字段掩码控制要返回的多段线:

  • 在路线级别,通过在响应字段掩码中添加 routes.polyline 来在响应中返回多段线。

  • 在路程级别上,通过添加 routes.legs.polyline,在响应的每个路线响应中返回多段线。

例如,要为整个路线和每条路程返回多段线,请使用以下代码:

X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline

配置多段线类型

computeRoutes 方法 (REST) 和 ComputeRoutes 方法 (gRPC) 支持使用 polylineEncoding 请求选项来控制多段线类型。

polylineEncoding 指定如何将多段线编码为 ENCODED_POLYLINE(默认),即使用多段线编码算法或 GEO_JSON_LINESTRING 表示使用 GeoJSON LineString 格式。

例如,在请求正文中:

{
  "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": "2019-10-15T15:01:23.045123456Z",
  ...
}

返回路况信息

您可以对响应进行配置,使其包含有关收费和可能的可用区限制的信息:

RouteTravelAdvisory 和 RouteLegTravelAdvisory 都包含一个数组,用于提供详细说明流量密度的车速信息。数组中的每个对象都由 SpeedReadingInterval (REST) 或 SpeedReadingInterval (gRPC) 对象表示。

SpeedReadingInterval 对象包含路线间隔的速度读数。整个对象数组可覆盖路线的整个多段线,而不会重叠。指定时间间隔的起点与上一时间间隔的终点相同。

要将该方法配置为通过多段线返回路况信息,请使用响应字段掩码

  • 在路由级别,通过将 routes.travelAdvisory 包含在响应字段掩码中,返回响应中的所有流量信息。如需仅返回 SpeedReadingInterval,请指定 routes.travelAdvisory.speedReadingIntervals

  • 在路程一级,通过添加 routes.legs.travelAdvisory.speedReadingIntervalsroutes.legs.steps.travelAdvisory.speedReadingIntervals,在路线的每个路段的响应中返回路况信息。

返回路况信息时,您通常在响应中同时返回多段线和路况信息:

X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.travelAdvisory,routes.legs.polyline,routes.legs.travelAdvisory

路况感知型折线的响应示例

在响应中,路由级流量可用于 routes.travelAdvisory.speedReadingIntervals。段级流量可在 routes.legs.travelAdvisory.speedReadingIntervals 下找到。

每个时间间隔由其 startPolylinePointIndexendPolylinePointIndex 和相应的速度类别描述。请注意,根据 proto3 做法,间隔内缺少起始索引对应于索引 0。

startPolylinePointIndexendPolylinePointIndex 值并不总是连续的。例如:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

在本例中,流量条件从索引 2 到索引 4 相同。

完整响应如下:

{
  "routes": [
    {
      "legs": {
        "polyline": {
          "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
        },
        "travelAdvisory": {
          "speedReadingIntervals": [
            {
              "endPolylinePointIndex": 1,
              "speed": "NORMAL"
            },
            {
              "startPolylinePointIndex": 1,
              "endPolylinePointIndex": 2,
              "speed": "SLOW"
            },
            {
              "startPolylinePointIndex": 2,
              "endPolylinePointIndex": 4,
              "speed": "NORMAL"
            }
          ] 
        }
      },
      "polyline": {
        "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
      },
      "travelAdvisory": {
        "speedReadingIntervals": [
          {
            "endPolylinePointIndex": 1,
            "speed": "NORMAL"
          },
          {
            "startPolylinePointIndex": 1,
            "endPolylinePointIndex": 2,
            "speed": "SLOW"
          },
          {
            "startPolylinePointIndex": 2,
            "endPolylinePointIndex": 4,
            "speed": "NORMAL"
          }
        ] 
      }
    }
  ]
}

使用 Maps SDK 渲染流量感知多段线

我们建议您使用 Google Maps SDK 提供的各种功能(包括自定义着色、描边和多段线沿线的图案)在地图上显示可感知路况的多段线。如需详细了解如何使用多段线,请参阅 Android 的多段线功能iOS 的多段线功能

多段线渲染示例

Maps SDK 的用户有机会在速度类别和多段线渲染架构之间定义自定义映射逻辑。例如,您可能会决定在地图上以粗蓝色线条显示“正常”速度,而以“慢”速度显示为粗橙色线,以此类推。

以下这段代码将会添加一条蓝色的粗多段线,其中包含从墨尔本至珀斯的测地线段。如需了解详情,请参阅自定义外观(对于 Android)和自定义多段线(对于 iOS)。

Android

Java

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

Kotlin

val line: Polyline = map.addPolyline(
  PolylineOptions()
    .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734))
    .width(25f)
    .color(Color.BLUE)
    .geodesic(true)
)

iOS

Objective-C

GMSMutablePath *path = [GMSMutablePath path];
[path addLatitude:-37.81319 longitude:144.96298];
[path addLatitude:-31.95285 longitude:115.85734];
GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
polyline.strokeWidth = 10.f;
polyline.strokeColor = .blue;
polyline.geodesic = YES;
polyline.map = mapView;

Swift

let path = GMSMutablePath()
path.addLatitude(-37.81319, longitude: 144.96298)
path.addLatitude(-31.95285, longitude: 115.85734)
let polyline = GMSPolyline(path: path)
polyline.strokeWidth = 10.0
polyline.geodesic = true
polyline.map = mapView