Trip Weather

本指南：按路线上的一组途经点，查询沿途天气风险。

功能介绍

Trip Weather 用于导航或算路之后，判断这条行程会不会遇到需要提醒的天气，例如强降水、大风、低能见度等道路风险。它查询的不是单个地点的预报，而是一组带到达时间的途经点。

能力由 WeatherClient.fetchRoadRisk() 提供。该接口是挂起函数，需要在协程中调用。

调用前需要完成 WeatherService.initialize()。已集成 Map SDK 时，可以不传 apiKey、apiSecret 和 baseUrl，SDK 会使用 Map SDK 中的云端凭证。独立集成时需要自行提供这三项。初始化示例见 Place Weather。

请求

RoadRiskRequest 包含 1–50 个途经点。每个途经点需要：

字段	说明
纬度、经度	路线上的采样位置
epochTime	预计到达该点的 Unix 时间，单位为秒

details 默认为 false。设为 true 时，响应会带上更完整的预警内容。

途经点应按行驶顺序排列，epochTime 使用该点的预计到达时间，而不是发请求的当前时间。

val epochTime = System.currentTimeMillis() / 1000 + 3600
val response = client.fetchRoadRisk(
    RoadRiskRequest.builder()
        .waypoint(37.77, -122.42, epochTime)
        .waypoint(37.80, -122.40, epochTime + 600)
        .details(true)
        .build()
)
if (response.status?.isOk() == true) {
    val roadRisks = response.data?.roadRisks
}

roadRisks 与请求中的途经点一一对应，顺序相同。每一项给出该点的天气、路面状况和预警；预警带有 type 和 tag，用于区分风险种类并决定是否向驾驶员展示。

结果与错误

先判断 response.status?.isOk()。成功状态码是 29200。传输失败不会抛到调用方，而是写在 status 里。字段说明与 SDK 模型注释一致。

响应外层 RoadRiskResponse

字段	类型	说明
status	WeatherResponseStatus?	接口状态。status 等于 29200 时表示成功
data	RoadRisks?	道路风险结果，含每个途经点的天气、路面状况和预警
expiredTimestamp	Long?	缓存过期时间戳，Unix 毫秒
expires	Long?	缓存过期时间，Unix 毫秒

WeatherResponseStatus：

字段	类型	说明
message	String?	状态说明，例如 OK、INVALID_PARAMETER
status	Int?	状态码。29200（WeatherStatusCodes.ALL_OK）表示成功

RoadRisks：

字段	类型	说明
roadRisks	List<RoadRisk>?	每个途经点的风险结果，顺序与请求一致

单个途经点 RoadRisk

字段	类型	说明
epochTime	Long?	该结果对应的时间，Unix 秒，回显请求中的 epochTime
geoPosition	GeoCoordinate?	该结果对应的位置，回显请求中的经纬度
weather	RoadRiskWeather?	该点在该时间的天气
road	RoadRiskCondition?	该点的路面状况
alerts	List<RoadRiskAlert>?	适用于该点的官方天气预警，没有时为空

GeoCoordinate：

字段	类型	说明
latitude	Double?	纬度，十进制度
longitude	Double?	经度，十进制度
elevation	MetricImperialObj?	海拔

RoadRiskWeather：

字段	类型	说明
weatherText	String?	简短天气描述，例如 overcast clouds
weatherIcon	Int?	天气图标标识
temperature	MetricImperialObj?	该点气温
wind	Wind?	风向和风速
precipitationIntensity	MetricImperialObj?	该点降水强度
dewPoint	MetricImperialObj?	露点温度

RoadRiskCondition：

字段	类型	说明
state	String?	路面状态。已知取值见下方 state 取值
temperature	MetricImperialObj?	路面温度

RoadRiskAlert：

字段	类型	说明
senderName	String?	预警发布方，例如 NWS
headline	String?	预警简短标题
type	String?	预警类别。已知取值见下方 type 取值
tag	String?	与预警关联的天气现象。已知取值见下方 tag 取值
level	Int?	预警等级，等级刻度由数据提供方决定

取值说明

RoadRiskCondition.state（RoadRiskConditionState）：

常量	取值	说明
NONE	None	未报告特殊路面风险
BLACK_ICE	BlackIce	报告黑冰风险

RoadRiskAlert.type（RoadRiskAlertType）是天气服务给出的风险大类：

常量	取值	说明
ROAD_CONDITION	RoadCondition	路面或行车条件预警，例如路滑
VISIBILITY	Visibility	能见度降低，例如雾、强降雨
WIND_RISK	WindRisk	与风有关的行车风险
WATER_RISK	WaterRisk	与水有关的风险，例如洪水、积水
TEMPERATURE	Temperature	极端温度，高温或低温
OTHER	Other	不属于以上类别的预警

RoadRiskAlert.tag（RoadRiskAlertTag）标识具体天气现象：

常量	取值	说明
COASTAL_EVENT	coastal_event	沿海天气事件，例如风暴潮、大浪
EXTREME_LOW_TEMPERATURE	extreme_low_temperature	极端低温
EXTREME_HIGH_TEMPERATURE	extreme_high_temperature	极端高温
WIND	wind	风
FLOOD	flood	洪水
SAND_DUST	sand_dust	沙尘暴
RAIN	rain	降雨
FIRE_WARNING	fire_warning	野火或火险天气
MARINE_EVENT	marine_event	海上天气事件
AVALANCHES	avalanches	雪崩
FOG	fog	雾
AIR_QUALITY	air_quality	空气质量
TORNADO	tornado	龙卷风
CYCLONE	cyclone	气旋或飓风
SNOW_ICE	snow_ice	雪或冰
THUNDERSTORM	thunderstorm	雷暴
HAIL	hail	冰雹

共用度量字段

类型	字段	说明
MetricImperial	value	数值
MetricImperial	unit	单位缩写，例如 C、F、km/h
MetricImperial	unitType	数据提供方的单位类型标识
MetricImperialObj	metric	公制
MetricImperialObj	imperial	英制
Wind	direction	风向。degrees 为 0–360 度，localized 为本地化名称，english 为英文名称
Wind	speed	风速

状态码

状态码	含义
29200	成功
29400	请求参数无效，例如途经点数量不在 1–50，或缺少经纬度、到达时间
29404	未找到数据
29900	客户端网络失败
29902	未能映射的 HTTP 传输错误

注意事项

• 途经点数量是 1–50。路线很长时，按距离或时间抽稀后再请求，不要把每个形状点都传上去。
• epochTime 用秒。传入毫秒会得到错误的到达时间。
• 只需要某一个地点的当前天气或预报时，使用 Place Weather，不要用本接口。
• 用完 SDK 后调用 WeatherService.dispose() 释放资源。

相关指南

• Place Weather
• SDK 简介