借助 annotatePaths 方法，您可以获取所请求道路上动态路况属性的注释。这些注解对于高级驾驶辅助系统 (ADAS) 的实现非常有用。
如需获取路径注释，您可以发送一个请求，其中应包含您要获取注释的路径列表，以及您希望在这些路径上获取的注释类型。响应中包含您之前请求的带注解数据的路径。响应中的路径带有注解，就像您发出请求时车辆正在行驶每条路径。
主要概念
以下小节介绍了了解 annotatePaths 方法的必要概念。
路径和细分
此方法会为路径数据添加注释，路径是车辆可能行驶的一系列已连接的路段。
下图展示了两条路径，每条路径都包含三段。
图 1. 路径 1（由段 A、B 和 C 段）以及路径 2（由段 A、B 和 D 组成）的示意图。
路径的长度上限为 15 公里，从第一个路段的起点到最后一个路段的起点测量。如果最后一个路段的起点与第一个路段的起点相距不到 15 公里，就会发生错误。
路径的起点始终是假定的车辆位置，一辆车辆可以有多个路径以不同位置结束，但路径不能从不同位置开始。
片段注解可能会因其所属的路径而异。即使两条路径共享一些相同的路段，这些路段的注释也可能不同。
例如，如图 1 所示：
路径 1 包含以下各项：
- 细分 A
- 细分 B
- 细分受众群 C
路径 2 包含以下各项：
- 细分 A
- 细分 B
- 细分受众群 D
在路径 1 中，细分 B 后跟细分 C，在路径 2 中，同一细分 B 后跟另一个细分，即细分 D。
细分 B 可能针对路径 1 和路径 2 返回不同的动态属性，因为路径 2 中的右转弯可能会比路径 1 中的直路径产生更高的流量。
服务等级
服务等级是一个通常使用的术语，用于描述预测的交通流根据车辆速度、密度、拥塞度和其他参数进行分类。请务必注意，此方法中使用的服务定义级别以及本文档中介绍的服务定义级别是该方法专有的专有级别。
以下列表介绍了所使用的服务级别。
| 服务等级 | 值 | 说明 |
|---|---|---|
LEVEL_OF_SERVICE_UNSPECIFIED
|
0 | 默认值。此值表示没有预测的流量值。 |
LEVEL_OF_SERVICE_STOPPED
|
1 | 交通已停止，且车辆未移动。 |
LEVEL_OF_SERVICE_STOP_AND_GO
|
2 | 交通拥堵，车辆低速行驶，不久后便停止。 |
LEVEL_OF_SERVICE_SLOW
|
3 | 预计交通拥堵，车辆行驶缓慢，但预计不会交通拥堵。 |
LEVEL_OF_SERVICE_NORMAL
|
4 | 路况正常，预计不会减速。 |
获取路径注解
如需获取路径注释，可以向 annotatePaths 方法 (REST) 发送 HTTP POST 请求，或调用 AnnotatePaths 方法 (gRPC)。
以下各小节介绍了用于请求和接收路径注解的请求和响应正文，以及指向 REST 引用的链接。
请求正文
annotatePaths 方法请求正文包含以下内容：
Paths：所请求的路线（路径集），要使用动态属性数据进行注解。该路线上的所有路径都应具有相同的起始路段，即车辆所在的路段。系统会假定车辆位于第一路段的起点。如果路径的起点并非同一段，系统将返回错误。Path：请求动态属性的路径。Segments：构成路径的线段的有序列表。Segment：属于路径的路段。Polyline：路段的多段线，在找不到 ID 时可用于识别相应路段。它还可用于区分具有相同 ID 的两个细分受众群。多段线采用标准的 Google Maps Platform 编码多段线算法格式进行编码。placeId：此路段的地点 ID，可与DirectionalSegment对象中placeId字段的值相同。
AnnotationOptions：为输入路径请求的注解。includeLevelOfService：布尔值字段。设置为 true 时，响应中的路段将使用预测的流量值进行注释。有关详情，请参阅本文档的服务级别部分。
请求要求
annotatePaths 方法的请求正文必须遵循以下要求：
- 各路径必须以同一段开头。
- 路径不得超过 15 公里，其中最后一段路的起点与第一段起点相距不超过 15 公里。
- 请求包含的路径必须包含不超过 10 个。
示例请求
以下示例展示了 annotatePaths 方法的请求正文。在此示例中，您将发送一条由三段组成的路径，并指明您想要包含服务级别注释。
paths {
segments {
place_id: "ChIJqZ402gQVkFQRcM9QM5EHX1A"
polyline {
encoded_polyline: "ojxaHfkviVuAjA_@l@y@jC"
}
}
segments {
place_id: "ChIJg_9y5AQVkFQRKL3E7_fPM_o"
polyline {
encoded_polyline: "_pxaHlsviVg@bB"
}
}
segments {
place_id: "ChIJle5mqwUVkFQRuhQhpqFyxRM"
polyline {
encoded_polyline: "gqxaHpvviV_EtM"
}
}
}
annotation_options {
include_level_of_service: true
}
响应正文
annotatePaths 方法响应正文包含以下内容：
annotatedPaths：输入中含有所请求属性注解的路径。AnnotatedPath：包含预测属性返回的输入路径的副本。annotatedSegments：构成主路径的线段的有序列表，并附有所请求的属性。AnnotatedSegment：用于构建路径的线段，带有动态数据属性注解。Segment：属于路径的线段。placeId：此路段的地点 ID，可与DirectionalSegment对象中placeId字段的值相同。
SegmentSpanAttributes：分配给细分的属性。 这些属性可能会因路段所在的路径而异。一段跨度可以覆盖整个片段。属性 span 将按向前顺序排列，从车辆位置到路径末尾。SegmentSpan：说明注释在片段上的适用位置。LevelOfService：路段跨度的预测交通水平，由车辆抵达路段起点时预计在此路段上的车流速度定义。如需了解详情，请参阅本文档的服务级别部分。
响应示例
以下示例展示了 annotatePaths 方法的请求正文。在此示例中，您会在示例请求中所请求的一个路径上收到服务注释级别。
annotated_paths {
annotated_segments {
segment {
place_id: "ChIJqZ402gQVkFQRcM9QM5EHX1A"
}
segment_span_attributes {
segment_span {
start_meters: 0
end_meters: 142
}
level_of_service: LEVEL_OF_SERVICE_NORMAL
}
}
annotated_segments {
segment {
place_id: "ChIJg_9y5AQVkFQRKL3E7_fPM_o"
}
segment_span_attributes {
segment_span {
start_meters: 0
end_meters: 44
}
level_of_service: LEVEL_OF_SERVICE_NORMAL
}
}
annotated_segments {
segment {
place_id: "ChIJle5mqwUVkFQRuhQhpqFyxRM"
}
segment_span_attributes {
segment_span {
start_meters: 0
end_meters: 206
}
level_of_service: LEVEL_OF_SERVICE_NORMAL
}
}
}