算路结果

1. 处理结果

算路任务执行完成后，回调参数为 RouteResponse。通过 response（Response<List<Route>>）获取状态与路线列表。成功时 response.result 含一条或多条 Route；每条 Route 由 TravelPoint、RouteLeg、RouteStep、RouteEdge 等组成，可表达起终点、途经点、道路网络、长度耗时、交通状态与道路提醒等信息。

1.1 路线模型

错误码（`response.status`）

response.status 取值来自 DirectionErrorCode。判断成功：

if (routeResponse.response.status == DirectionErrorCode.OK) {
    val routes = routeResponse.response.result
}

错误码	值	说明
`OK`	0	算路成功
`FAILURE`	1	内部错误或初始化失败
`CANCELLED`	5	用户取消导致算路失败
`BASE_MAP_DATA_ERROR`	100	本地基础地图数据异常
`STREAMING_MAP_DATA_ERROR`	101	流式地图数据异常
`INVALID_MAP_CONTENT`	102	MapContent 服务未按预期工作
`ORIGIN_BLOCKED_BY_TRAFFIC`	103	起点因交通封闭不可达
`ORIGIN_BLOCKED_BY_RESTRICTION`	104	起点因道路限制不可达
`INVALID_REQUEST`	105	请求参数无效
`INVALID_ENERGY_CONSUMPTION_MODEL`	106	能耗模型无效（EV 相关场景）
`CLOUD_SERVICE_ERROR`	107	云端服务返回错误
`NETWORK_TRANSACTION_ERROR`	108	网络请求未正常完成
`OPERATION_ABORTED_BY_CONTENT_SWITCH`	109	地图内容切换导致操作中止；可在 MapContent 切换完成后再重试
`UNKNOWN_ERROR`	10000	未知错误

处理建议：

错误码	建议
`OK`	读取 `response.result` 获取路线
`CANCELLED`	用户主动取消，无需重试
`INVALID_REQUEST`	检查起终点、`RouteRequest` 参数是否完整合法
`ORIGIN_BLOCKED_BY_TRAFFIC` / `ORIGIN_BLOCKED_BY_RESTRICTION`	提示用户调整起点位置
`BASE_MAP_DATA_ERROR` / `STREAMING_MAP_DATA_ERROR` / `INVALID_MAP_CONTENT`	检查地图数据目录、网络及 SDK 初始化状态
`CLOUD_SERVICE_ERROR` / `NETWORK_TRANSACTION_ERROR`	检查网络、鉴权与 `CloudEndPoint` 配置
`OPERATION_ABORTED_BY_CONTENT_SWITCH`	等待内容切换完成后重新发起算路
`INVALID_ENERGY_CONSUMPTION_MODEL`	检查 `VehicleInfoProvider` 中的能耗/EV 配置
其它	记录 status 值，结合日志排查或重试

RouteResponse

RouteResponse 是算路任务返回的结果对象。使用路线数据前，应先判断 response.status == DirectionErrorCode.OK（见上文错误码），并确认 response.result 非空；多路线场景可遍历列表展示备选方案。

字段	说明
`response.status`	算路结果状态码（`DirectionErrorCode`）；`OK` 表示成功
`response.result`	候选路线列表 `List<Route>`；仅当 `status == OK` 时有效

Route

Route 是从起点到终点（或经若干途经点）的完整路线顶层对象；有途经点时按 leg 分段，无途经点时仅含一个 leg。

基础距离与时间

方法 / 属性	说明
`length`	路线总长度（米）
`duration`	考虑交通后的预计耗时（秒）
`durationWithoutTraffic`	不考虑交通的预计耗时（秒）；可能大于 `duration`（部分路况下交通表示更快）
`trafficDelay`	路线总延误时间（秒）
`trafficLightCount`	沿途交通灯数量
`routeStyle`	路线风格（`RouteStyle`）
`isCloudRoute`	是否为云端算路结果

标识、内容与引导阶段

方法 / 属性	说明
`id`	路线唯一标识；基于几何、引导信息、算路时间等生成；序列化/反序列化后不变
`sessionId`	路线会话逻辑 ID；同一会话内引导或 ETA 更新后可能产生新 `Route` 对象但 `sessionId` 相同
`guidanceStage`	增量引导计算阶段（`GuidanceStage`）

guidanceStage 取值说明：

NO_GUIDANCE：当前路线还未计算出引导信息。
PARTIAL_GUIDANCE：当前路线已计算出部分引导信息。
FULL_GUIDANCE：当前路线已计算出全程完整引导信息。

不同求路模式下的常见行为：

Cloud 求路： 通常直接返回 FULL_GUIDANCE。
Onboard 求路： 通常返回 NO_GUIDANCE 或 PARTIAL_GUIDANCE。
进入导航后： SDK 会继续补全引导；当引导补全到完整阶段时，会通过 onNavigationRouteUpdating 接口返回最新路线（见换路通知）。

结构与途经点

方法 / 属性	说明
`routeLegList`	路线分段列表；无途经点时仅 1 个 leg，有途经点时按起点—途经点—终点拆分
`travelPoints`	沿途行驶点列表（含起点与终点），顺序与行驶方向一致；至少 2 个点，与各 leg 终点对应

到达时间、封闭路与安全

方法 / 属性	说明
`arrivalTimes`	各途经点及终点的本地到达时间；EV 路线含充电时长。格式 `yyyy-MM-dd HH:mm:ss`
`trafficClosures`	交通封闭路段的边索引列表；仅在 `avoidTrafficClosures == false` 且无法绕行时出现
`safetyScore`	路线安全评分（0.0–100.0）；需在 `RoutePreferences` 中启用 `enableRouteSafety`；无法计算时为 -1

EV / 能耗（按需使用）

方法 / 属性	说明
`estimatedReachableLength`	按当前电量与充电计划可行驶的预估长度（米）；仅 EV 行程规划场景有效，可能小于 `length`
`unreachableEdgeIndex`	无法到达的第一条边的索引；可达时为 `null`
`energyConsumption`	全程预估燃油能耗；非电动车返回正值，电动车返回 `0.0`

限制与元数据

方法 / 属性	说明
`truckRestrictionRecords`	沿途商用车限制记录（物理/法规限制及位置）；算路会尽量规避，必经时仍会返回说明
`edgeRestrictionInfos`	沿途道路限制信息（如门禁、通行限制等）及对应边索引
`routeMetaInfo`	路线附加元信息（`RouteMetaInfo`）；无数据时为 `null`

收费

该接口仅在地图数据支持收费路段与费用信息时才能返回有效结果。集成前建议先确认当前项目所用地图数据是否覆盖目标区域及字段（收费区间、金额、货币等）。

方法	说明
`getTollSegments()`	获取沿当前路线行驶的预估收费路段列表（`List<TollSegment>?`）

getTollSegments() 返回值语义：

返回值	说明
非空列表	数据加载成功；列表中每项为一段收费区间
空列表	数据加载成功，但当前路线无收费
`null`	收费路段数据无法加载，例如 native route handle 无效、JNI 编码失败或数据尚未加载完成

每条 TollSegment 通过 startIndex 与 endIndex（均为 RouteEdgeIndex）标识收费区间，区间为闭区间 [startIndex, endIndex]。收费路段可能跨越多个 RouteLeg。仅存在 startIndex（endIndex 为 null）时，表示进入该 edge 即开始收费。

TollSegment

字段	类型	说明
`fees`	`List<TollFee>?`	当前收费路段的费用明细；`null` 表示费用未知或地图数据未提供。地图数据可能返回多种货币或计费方案，因此列表中可含多项
`startIndex`	`RouteEdgeIndex?`	收费区间起点 edge；`null` 表示起点未知。native 层返回的实例通常非空
`endIndex`	`RouteEdgeIndex?`	收费区间终点 edge；`null` 表示终点未知。与 `startIndex` 相同时，费用仅作用于单个 edge（如桥梁、收费站）

RouteEdgeIndex 由 legIndex、stepIndex、edgeIndex 组成（均从 0 起），分别相对路线、leg、step 定位 edge。

TollFee

字段	类型	说明
`currencyCode`	`String`	ISO 4217 货币代码（如 `"USD"`、`"EUR"`）；空字符串表示数据异常，应按错误情况处理
`fee`	`Float`	以 `currencyCode` 计价的收费金额；地图数据未提供精确金额时默认为 `-1.0f`

序列化与释放

方法 / 属性	说明
`serialization()`	将 `Route` 序列化为 `ByteArray`
`Route.RouteBuilder.deSerialization(buffer)`	从 `serialization()` 得到的字节数组还原 `Route`；失败返回 `null`
`dispose()`	释放当前 `Route` 占用的 native 资源；不再使用时调用

TravelPoint

TravelPoint 表示路线中的出行点（起点、途经点、终点），顺序与行驶方向一致。
除位置本身外，TravelPoint 还携带时区与（EV 场景下）充电计划信息。

字段	说明	典型用途
`location`	当前出行点的 `GeoLocation`	地图打点、地点信息展示
`timeZoneInfo`	当前出行点时区信息	本地到达时间展示、跨时区行程展示
`autoPlanned`	是否由智能规划自动插入（例如 EV 自动规划充电点）	在 UI 区分“用户手动加点”与“系统自动补点”
`chargingPlan`	当前点的充电动作计划（仅在该点有充电计划时有效）	EV 场景展示充电时长、到达/离开电量等

使用建议：

通用导航可直接读取 Route.arrivalTimes（yyyy-MM-dd HH:mm:ss）展示到达时刻。
EV 导航若 travelPoint.chargingPlan != null，说明该点包含计划充电动作；充电站静态详情（品牌、营业时间、配套）建议再通过 location.placeId 到实体服务查询。

val travelPoints = route.travelPoints
val arrivalTimes = route.arrivalTimes

for ((index, point) in travelPoints.withIndex()) {
    val eta = arrivalTimes.getOrNull(index)
    val isAutoPoint = point.autoPlanned
    val hasChargingAction = point.chargingPlan != null
    // 用于 HMI：显示 ETA、是否自动补点、是否有充电动作
}

RouteLeg

RouteLeg 表示两个相邻出行点之间的一段路线，例如起点到第一个途经点、两个途经点之间、最后一个途经点到终点。一般情况下，routeLegList 数量比 travelPoints 少 1。每个 RouteLeg 包含一个或多个 RouteStep。

属性	说明
`length`	当前分段长度（米）
`duration`	当前分段耗时（秒，含交通）
`durationWithoutTraffic`	当前分段耗时（秒，不含交通）
`trafficLightCount`	当前分段交通灯数量
`routeStepList`	当前分段中的引导步骤列表
`characteristic`	当前分段道路特征或提醒（如含收费路、轮渡等），见下文
`majorSegments`	当前分段主要道路名称，可用于路线摘要（如「经由某某路」）
`nearbyRestAreaEntries`	路线附近服务区入口列表（启用 `enableServiceRoadEntries` 时）

RouteCharacteristic（`characteristic`）

characteristic 表示当前 RouteLeg 经过道路的特征、通知或提醒，取值为 RouteCharacteristic 常量列表。应用可将其转化为用户可见的提示文案。

val characteristics = route.routeLegList.first().characteristic ?: emptyList()
val warnings = mutableListOf<String>()
for (c in characteristics) {
    when (c) {
        RouteCharacteristic.HAS_TOLL -> warnings.add("该路线包含收费道路。")
        RouteCharacteristic.HAS_FERRY -> warnings.add("该路线包含轮渡。")
        RouteCharacteristic.HAS_HIGHWAY -> warnings.add("该路线包含高速。")
        // 其它特征见 RouteCharacteristic
    }
}

majorSegments（主要道路名称）

majorSegments 表示当前 RouteLeg 中占比较高或更重要的道路名称列表，可用于生成路线摘要。

val majorRoads = route.routeLegList.first().majorSegments ?: emptyList()
val viaRoads = if (majorRoads.isNotEmpty()) {
    "经由 ${majorRoads.joinToString("、")}"
} else {
    ""
}

nearbyRestAreaEntries（沿途服务区入口）

RestAreaEntry 字段说明：

字段	说明
`location`	服务区入口坐标（`LatLon`）
`connectedRoadId`	该入口连接的统一道路段 ID
`type`	服务区类型（`RestAreaType`）
`distance`	从起点沿主路线到“引导进入该服务区的出口”距离（米）；不包含出口到服务区入口的连接段距离
`eta`	从起点沿主路线到同一出口的预计时间（秒）；不包含出口到服务区入口的连接段时间

RestAreaType 取值说明：

枚举值	value	说明
`OTHERS`	0	兜底类型，不属于以下明确分类
`COMPLETE_REST_AREA`	1	完整服务区（设施较完整）
`PARKING_AND_REST_ROOM_ONLY`	2	仅停车 + 卫生间
`PARKING_ONLY`	3	仅停车
`MOTORWAY_SERVICE_AREA`	4	高速公路服务区（MSA）
`SCENIC_OVERLOOK`	5	观景停靠点

RouteStep

RouteStep 表示路线中需要用户执行一次引导动作的道路片段（如直行、转弯、进入/驶出道路）。一个 RouteLeg 通常由多个 RouteStep 组成，每个 Step 包含机动信息、道路名及更细粒度的 RouteEdge 列表。

按 RouteStep.kt，其核心字段如下：

字段	说明	典型用途
`routeEdgeList`	当前 step 的 edge 列表	继续展开读取几何、路型、交通快照等
`roadNameList`	当前 step 道路名称列表（`Name`）	生成“当前路/下一路”文案
`maneuverInfo`	当前机动动作（`Maneuver`，含 action/assistAction/lane/signposts）	Turn-by-turn 图标与引导文案
`leftSideDriving`	是否左侧通行	用于调整车道/转向展示逻辑
`length`	当前 step 总长度（米）	机动间距与预告距离计算
`countryCode`	当前 step 所在国家 ISO 码	跨境场景规则、文案本地化
`trafficLightCount`	当前 step 内交通灯数量	风险提醒、驾驶负荷提示

说明：

maneuverInfo 可能为空（例如仅结果级数据或尚未补全引导阶段），使用时需判空。

当前 / 下一道路名（`roadNameList`）

转向引导中的当前道路名和下一道路名可从相邻 RouteStep 的 roadNameList 获取。Name 包含 type（如 NameType.OFFICIAL）、format 及 orthography.content 等；展示时通常选择官方名称格式。

fun findDisplayName(names: List<Name>?): String? {
    return names?.firstOrNull { name ->
        name.type == NameType.OFFICIAL &&
            name.format == NameFormat.NAME
    }?.orthography?.content
}

val steps = route.routeLegList.first().routeStepList ?: emptyList()
for (i in steps.indices) {
    val currentRoad = findDisplayName(steps[i].roadNameList)
    val nextRoad = if (i < steps.size - 1) {
        findDisplayName(steps[i + 1].roadNameList)
    } else {
        null
    }
    // 使用 currentRoad、nextRoad 展示转向文案
}

RouteEdge

RouteEdge 是路线中最基础的道路片段，与地图道路段概念相近，仅保留路线展示与导航所需的必要信息。

RouteEdge 通常可用于：

获取道路片段长度（length）
获取道路片段 ID（edgeId / getWayId()）
获取路线几何形状（getEdgeShapePoints()），用于绘制路线
获取算路时刻的交通状态快照（liveTrafficLevel、trafficFlow）

注意： RouteEdge 中的交通状态是算路时的快照。如需展示最新交通，应重新查询实时交通或重新算路。

1.2 示例

task.runSync { routeResponse ->
    when (routeResponse.response.status) {
        DirectionErrorCode.OK -> {
            for (route in routeResponse.response.result ?: emptyList()) {
                val length = route.length
                val duration = route.duration
                // 读取 edge geometry，用于地图绘制
                val geometry = mutableListOf<LatLon>()
                for (leg in route.routeLegList) {
                    for (step in leg.routeStepList ?: emptyList()) {
                        for (edge in step.routeEdgeList ?: emptyList()) {
                            edge.getEdgeShapePoints()?.let { geometry.addAll(it) }
                        }
                    }
                }
            }
        }
        DirectionErrorCode.CANCELLED -> {
            // 用户已取消
        }
        DirectionErrorCode.ORIGIN_BLOCKED_BY_TRAFFIC,
        DirectionErrorCode.ORIGIN_BLOCKED_BY_RESTRICTION -> {
            // 提示用户调整起点
        }
        DirectionErrorCode.NETWORK_TRANSACTION_ERROR,
        DirectionErrorCode.CLOUD_SERVICE_ERROR -> {
            // 检查网络与云端配置
        }
        else -> {
            // 其它错误，参见上文错误码表
        }
    }
    task.dispose()
}