借助 annotatePaths 方法，您可以获取有关您请求的道路路径上的动态路况属性的注释。这些注释对于高级驾驶辅助系统 (ADAS) 的实现非常有用。
要获取路径注释，您可以发送一个请求，其中包含您要获取其注释的路径列表，以及您想要在这些路径上添加哪些类型的注释。响应包含您之前请求的带注释数据的路径。响应中的路径带有注解，就像在您发出请求时车辆在每条路径上行驶。
主要概念
以下各小节介绍了理解 annotatePaths 方法的必要概念。
路径和细分
此方法会为路径上的数据添加注释，路径是车辆可能行驶的一系列相连路段。
下图展示了两条路径，每条路径均由三个路段组成。
图 1. 路径 1 的示意图，包括段 A、B、C 以及路径 2，路径 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 可能会覆盖整个片段。属性 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
}
}
}