请求路线多段线

computeRoutes 方法 (REST) 和 ComputeRoutes 方法 (gRPC) 均返回由多段线表示的路线作为 响应。这些 API 会返回两种类型的多段线:

  • 基本多段线(默认),表示没有交通的路线 嵌入多段线中的信息返回基本多段线的请求 都是按路线基本费率结算的详细了解 billing

  • 路况感知多段线,包含路况信息 信息。用速度来表示路况 在指定时间间隔内适用的类别(NORMALSLOWTRAFFIC_JAM) 绘制多段线的形状对路况感知多段线的请求按 路由首选速率。详细了解 Routes API。有关详情,请参阅 配置多段线的质量

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

请求路线、路程或路段的基本多段线

多段线用 多段线 (REST) 或 多段线 (gRPC) 对象。 您可以在响应中返回路线、路程和路段级别的多段线。

使用 响应字段掩码

  • 在路线级别,通过以下方法在响应中返回多段线: 响应字段掩码中的 routes.polyline

  • 在路程级别,系统会针对 添加 routes.legs.polyline 进行路由。

  • 在路段级别,在 添加 routes.legs.steps.polyline

例如,要为整个路线、每条路程以及 每条路程的每一步:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

此请求会返回以下响应,其中包含 对于路线的每段路程和路程的每段路程:

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
              "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
          }
        },
          "steps": [
              {
                  "polyline": {
                      "encodedPolyline": "kclcF...@sC@YIOKI"
                  }
              },
              {
                  "polyline": {
                      "encodedPolyline": "wblcF~...SZSF_@?"
                  }
              },
              ...
      ],
      "distanceMeters": 56901,
      "duration": "2420s",
      "polyline": {
        "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
      }
    }
  ]
}

由于此请求仅包含起点和终点,因此返回的 路线只包含一段路程。因此,该分支的多段线 都一样

如果您向请求添加中间路标,则返回的 路线包含两条路程:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "intermediates": [
    { "address": "450 Serra Mall, Stanford, CA 94305, USA"},
  ],
  "travelMode": "DRIVE",
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

此请求返回两条腿,每条有一条唯一的多段线,多段线用于 整条路线:

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
            "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "kclcFfqch...YIOKI"
                }
            },
        ...
        },
        {
          "polyline": {
            "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "uypeFbo`jVgJq...PoBiC"
                }
            },
        ...
        }
      ],
      "distanceMeters": 68403,
      "duration": "3759s",
      "polyline": {
          "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE"
      }
    }
  ]
}

多段线质量

多段线的质量可以用以下术语描述:

  • 数据点的浮点精度

    点以纬度和经度值的形式指定, 单精度浮点格式。这种方法非常适合较小的值 (可以精确地表示),但精度会随值而降低 会由于浮点舍入误差而增加。

    computeRoutes 方法 (REST) 和 ComputeRoutes、 此控件由 polylineEncoding 控制。

  • 组成多段线的点数量

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

    computeRoutes 方法 (REST) 和 ComputeRoutes、 此控件由 polylineQuality 控制。

配置多段线编码类型

使用 polylineEncoding 请求选项来控制多段线类型。 polylineEncoding 属性用于控制多段线是否编码为 ENCODED_POLYLINE(默认值),表示 编码多段线算法格式 (即 GEO_JSON_LINESTRING),表示 GeoJSON LineString 格式

例如,在请求正文中:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "polylineEncoding": "ENCODED_POLYLINE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

配置多段线质量

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",
  ...
}

请求路况感知多段线

以上所示示例均返回基本的多段线,即未加工的多段线 路况信息此外,您还可以请求多段线包含 为路线和路线的每段路程提供路况信息。

路况感知型多段线包含路况信息以及 路径。用速度类别表示路况信息 (NORMALSLOWTRAFFIC_JAM)在指定的响应时间间隔内 多段线间隔由其起始索引(含)定义 和结束(不含)折线点之间的距离。

例如,以下响应显示了多段线之间的 NORMAL 路况 第 2 点和第 4 点:

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

要发出计算路况感知多段线的请求,请设置以下 属性:

  • extraComputations 数组字段设置为 TRAFFIC_ON_POLYLINE 即可启用 流量计算。

  • travelMode 设置为 DRIVETWO_WHEELER。针对任何其他 出行方式会返回错误。

  • 指定 TRAFFIC_AWARETRAFFIC_AWARE_OPTIMAL 路由 偏好设置。有关详情,请参阅配置质量与 延迟时间

  • 设置指定返回响应属性的响应字段掩码:

    • 在路线级别,通过以下方式在响应中返回所有出行信息: 在响应字段掩码中包含 routes.travelAdvisory。退货 仅查看路况信息、指定 routes.travelAdvisory.speedReadingIntervals

    • 在路段级别,在对以下地点的响应中返回所有行程信息: 添加 routes.legs.travelAdvisory。退货 仅查看路况信息、指定 routes.legs.travelAdvisory.speedReadingIntervals

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "extraComputations": ["TRAFFIC_ON_POLYLINE"],
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

路况感知多段线的响应示例

在响应中,路况数据会在折线中编码,并包含在 travelAdvisory 字段,类型为 RouteLegTravelAdvisory 对象(每条路程)和 RouteTravelAdvisory 对象(路线)。

例如:

{
  "routes": [
    {
      "legs": {
        "polyline": {
          "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
        },
        // Traffic data for the leg.
        "travelAdvisory": {
          "speedReadingIntervals": [
            {
              "endPolylinePointIndex": 1,
              "speed": "NORMAL"
            },
            {
              "startPolylinePointIndex": 1,
              "endPolylinePointIndex": 2,
              "speed": "SLOW"
            },
            {
              "startPolylinePointIndex": 2,
              "endPolylinePointIndex": 4,
              "speed": "NORMAL"
            }
          ] 
        }
      },
      "polyline": {
        "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
      },
      // Traffic data for the route.
      "travelAdvisory": {
        "speedReadingIntervals": [
          {
            "endPolylinePointIndex": 1,
            "speed": "NORMAL"
          },
          {
            "startPolylinePointIndex": 1,
            "endPolylinePointIndex": 2,
            "speed": "SLOW"
          },
          {
            "startPolylinePointIndex": 2,
            "endPolylinePointIndex": 4,
            "speed": "NORMAL"
          }
        ] 
      }
    }
  ]
}

RouteTravelAdvisoryRouteLegTravelAdvisory 都包含数组字段 名为 speedReadingIntervals,其中包含交通速度信息。每个 数组中的对象由 SpeedReadingInterval (REST) 或 SpeedReadingInterval (gRPC) 对象。

SpeedReadingInterval 对象包含路线间隔时间内的速度读数, 例如 NORMALSLOWTRAFFIC_JAM。整个对象数组涵盖 不重叠的整条路线。指定的 间隔与前一个间隔的终点相同。

每个间隔都由其 startPolylinePointIndex 描述, endPolylinePointIndex 和相应的速度类别。 请注意,间隔中缺少起始索引对应于索引 0 相关条款 proto3 做法

startPolylinePointIndexendPolylinePointIndex 值 始终连续。例如:

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

在本例中,从索引 2 到索引 4 的流量条件没有变化。

使用 Maps SDK 渲染可感知路况的多段线

我们建议使用各种 Google Maps SDK 提供的功能,包括自定义着色、描边和 沿多段线延伸的图案。有关使用多段线的更多详情,请参阅 请参阅 适用于 Android 的多段线功能 以及适用于 iOS 的多段线功能

多段线渲染示例

Maps SDK 的用户有机会定义自定义地图 速度类别与多段线渲染架构之间的逻辑关系。作为 例如,某用户可能会决定将“NORMAL”蓝色粗线 在“慢速”模式下速度可能显示为一条橙色的粗线。

以下代码段将添加一条蓝色的粗多段线,其中有一条测地线段从 从墨尔本到珀斯如需了解详情,请参阅 自定义外观 (适用于 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