Skip to content

Place Weather

本指南：按经纬度查询某一地点的当前天气、逐小时预报和逐日预报。

功能介绍

Place Weather 用于展示某个地点的天气，不依赖当前导航路线。典型场景包括目的地天气、搜索结果天气，以及地图上某一点的天气卡片。

能力由 Weather Service SDK 的 WeatherClient 提供，三个接口都是挂起函数，需要在协程中调用。

能力 接口 说明
当前天气 getCurrentCondition 观测时刻的天气现象、温度、降水、风等
逐小时预报 getHourlyForecast 从当前时刻起，最多 72 小时
逐日预报 getDailyForecast 从当前日期起，最多 10 天

调用前需要完成 WeatherService.initialize()。已集成 Map SDK 时，可以不传 apiKey、apiSecret 和 baseUrl，SDK 会使用 Map SDK 中的云端凭证，并在云端地址后拼接 /weather/api/v1。独立集成时需要自行提供这三项。

1
2
3
4
5
6
7
8
WeatherService.initialize(
    WeatherServiceOptions.builder()
        .apiKey("your-api-key")
        .apiSecret("your-api-secret")
        .baseUrl("https://<host>/weather/api/v1/")
        .build()
)
val client = WeatherService.getWeatherClient()

当前天气

CurrentConditionRequest 至少需要纬度和经度。

1
2
3
4
5
6
7
8
9
val response = client.getCurrentCondition(
    CurrentConditionRequest.builder()
        .latitude(37.77)
        .longitude(-122.42)
        .build()
)
if (response.status?.isOk() == true) {
    val condition = response.data
}

response.data 为当前天气。界面上常用的字段包括天气描述、天气图标、温度、是否有降水、相对湿度、风，以及观测点所在城市。响应里的 expires 表示该结果的建议缓存时长。

逐小时预报

hourlyLength 取值 1–72，表示返回的小时数。offset 从 0 起，表示跳过开头的若干小时；不传时为 0。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
val response = client.getHourlyForecast(
    HourlyForecastRequest.builder()
        .latitude(37.77)
        .longitude(-122.42)
        .hourlyLength(24)
        .offset(2) // 跳过前 2 小时
        .build()
)
if (response.status?.isOk() == true) {
    val hours = response.data?.hourlyForecasts
}

每个小时包含时间、天气图标与描述、温度、降水概率，以及雨、雪、冰的概率。

逐日预报

dailyLength 取值 1–10，表示返回的天数。offset 含义与逐小时预报相同。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
val response = client.getDailyForecast(
    DailyForecastRequest.builder()
        .latitude(37.77)
        .longitude(-122.42)
        .dailyLength(5)
        .build()
)
if (response.status?.isOk() == true) {
    val days = response.data?.dailyForecasts
}

每一天包含日期、最高与最低温度，以及白天、夜间的天气描述和降水概率。

结果与错误

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

响应外层

GetCurrentConditionResponse、HourlyForecastResponse、DailyForecastResponse 的外层字段相同，data 的类型不同。

字段 类型 说明
status WeatherResponseStatus? 接口状态。status 等于 29200 时表示成功
data 见下方各接口 当前天气为 CurrentCondition；逐小时为 HourlyForecasts；逐日为 DailyForecasts
expiredTimestamp Long? 缓存过期时间戳，Unix 毫秒
expires Long? 缓存过期时间，Unix 毫秒

WeatherResponseStatus：

字段 类型 说明
message String? 状态说明，例如 OK、INVALID_PARAMETER
status Int? 状态码。29200（WeatherStatusCodes.ALL_OK）表示成功
状态码 含义
29200 成功
29400 请求参数无效
29404 未找到数据
29900 客户端网络失败
29902 未能映射的 HTTP 传输错误

当前天气 CurrentCondition

字段 类型 说明
localObservationDateTime String? 本地观测时间，ISO-8601
epochTime Long? 观测时间，Unix 秒
weatherText String? 天气描述，例如 “overcast clouds”
weatherIcon Int? 天气图标标识
hasPrecipitation Boolean? 观测时刻是否正在降水
precipitationType String? 降水类型。hasPrecipitation 为 true 时有效，例如 Rain、Snow
isDayTime Boolean? 观测是否发生在白天
temperature MetricImperialObj? 气温
realFeelTemperature MetricImperialObj? 体感温度，已计入湿度和风
realFeelTemperatureShade MetricImperialObj? 阴凉处体感温度
apparentTemperature MetricImperialObj? 表观温度
windChillTemperature MetricImperialObj? 风寒温度
wetBulbTemperature MetricImperialObj? 湿球温度
dewPoint MetricImperialObj? 露点温度
relativeHumidity Int? 相对湿度百分比，0–100
wind Wind? 风向和风速
windGust MetricImperialObj? 阵风风速
uvIndex Int? 紫外线指数
uvIndexText String? 紫外线指数等级，例如 Low、Moderate
visibility MetricImperialObj? 水平能见度
obstructionsToVisibility String? 影响能见度的因素，例如雾、霾
cloudCover Int? 云量百分比，0–100
pressure MetricImperialObj? 观测时刻的气压
pressureTendency PressureTendency? 气压变化趋势
precip1hr MetricImperialObj? 过去 1 小时降水量
precipitationSummary PrecipitationSummary? 多个时间窗口的累计降水量
temperatureSummary TemperatureSummary? 多个时间窗口的温度最低、最高值
city WeatherLocation? 观测点位置信息

逐小时预报

HourlyForecasts：

字段 类型 说明
hourlyForecasts List<HourlyForecast>? 逐小时预报列表
city WeatherLocation? 预报位置信息

HourlyForecast：

字段 类型 说明
dateTime String? 预报时间，ISO-8601
epochDateTime Long? 预报时间，Unix 秒
weatherIcon Int? 天气图标标识
iconPhrase String? 简短天气描述
hasPrecipitation Boolean? 是否预期有降水
precipitationType String? 降水类型。hasPrecipitation 为 true 时有效，例如 rain、snow、ice
isDayLight Boolean? 该小时是否处于白天
temperature MetricImperialObj? 预报气温
realFeelTemperature MetricImperial? 体感温度，已计入湿度和风
dewPoint MetricImperial? 露点温度
wetBulbTemperature MetricImperial? 湿球温度
wind Wind? 风向和风速
windGust Wind? 阵风的风向和风速
relativeHumidity Int? 相对湿度百分比，0–100
visibility MetricImperial? 水平能见度
ceiling MetricImperial? 云底高度
uvIndex Int? 紫外线指数
uvIndexText String? 紫外线指数等级，例如 Low、Moderate
precipitationProbability Int? 综合降水概率百分比，0–100
rainProbability Int? 降雨概率百分比，0–100
snowProbability Int? 降雪概率百分比，0–100
iceProbability Int? 冻雨或结冰概率百分比，0–100
cloudCover Int? 云量百分比，0–100
totalLiquid MetricImperial? 液态降水总量
rain MetricImperial? 降雨量
snow MetricImperial? 降雪量
ice MetricImperial? 冻雨或结冰量

逐日预报

DailyForecasts：

字段 类型 说明
headline DailyForecastHeadline? 可选的预报摘要或预警标题
dailyForecasts List<DailyForecast>? 逐日预报列表
city WeatherLocation? 预报位置信息

DailyForecast：

字段 类型 说明
date String? 预报日期，ISO-8601
epochDate Long? 预报日期，Unix 秒
sun SunMoon? 日出、日落
moon SunMoon? 月出、月落和月相
temperature MetricImperialObjMinMax? 气温最低值和最高值
realFeelTemperature MetricImperialMinMax? 体感温度最低值和最高值
realFeelTemperatureShade MetricImperialMinMax? 阴凉处体感温度最低值和最高值
airAndPollen List<AirAndPollen>? 空气质量和花粉
hoursOfSun Double? 预期日照小时数
day DayPeriod? 白天预报
night DayPeriod? 夜间预报

DayPeriod（day 与 night）：

字段 类型 说明
icon Int? 天气图标标识
weatherText String? 天气描述
shortPhrase String? 简短天气摘要
longPhrase String? 较长天气摘要
precipitationProbability Int? 综合降水概率百分比，0–100
rainProbability Int? 降雨概率百分比，0–100
snowProbability Int? 降雪概率百分比，0–100
iceProbability Int? 冻雨或结冰概率百分比，0–100
thunderstormProbability Int? 雷暴概率百分比，0–100
hoursOfPrecipitation Double? 预期有降水的小时数
hoursOfRain Double? 预期降雨小时数
hoursOfSnow Double? 预期降雪小时数
hoursOfIce Double? 预期冻雨或结冰小时数
rain MetricImperial? 降雨量
snow MetricImperial? 降雪量
ice MetricImperial? 冻雨或结冰量
totalLiquid MetricImperial? 液态降水总量
wind Wind? 风向和风速
windGust Wind? 阵风的风向和风速
cloudCover Int? 云量百分比，0–100

DailyForecastHeadline：

字段 类型 说明
effectiveDate String? 生效开始时间，ISO-8601
effectiveEpochDate Long? 生效开始时间，Unix 秒
severity Int? 摘要严重程度
text String? 摘要正文
category String? 摘要类别，例如 thunderstorm
endDate String? 结束时间，ISO-8601
endEpochDate Long? 结束时间，Unix 秒
sources List<String>? 摘要数据来源

SunMoon：

字段 类型 说明
rise String? 升起时间，ISO-8601
epochRise Long? 升起时间，Unix 秒
set String? 落下时间，ISO-8601
epochSet Long? 落下时间，Unix 秒
phase String? 月相描述，仅月亮有值
age Int? 月龄，单位天，仅月亮有值

AirAndPollen：

字段 类型 说明
name String? 指标名称，例如 AirQuality、Grass、Tree
value Int? 数值
category String? 等级，例如 Good、Moderate
categoryValue Int? 数据提供方的等级编码
type String? 指标类型

共用度量字段

MetricImperialObj 同时给出公制和英制。MetricImperial 是单一单位的数值。

类型 字段 说明
MetricImperial value 数值
MetricImperial unit 单位缩写，例如 C、F、km/h
MetricImperial unitType 数据提供方的单位类型标识
MetricImperialObj metric 公制
MetricImperialObj imperial 英制
MetricImperialMinMax minimum / maximum 单一单位的最低值、最高值
MetricImperialObjMinMax minimum / maximum 同时含公制和英制的最低值、最高值
Wind direction 风向。degrees 为 0–360 度，localized 为本地化名称，english 为英文名称
Wind speed 风速
PressureTendency localizedText 本地化的气压趋势描述
PressureTendency code 数据提供方的趋势编码
PrecipitationSummary precipitation 当前降水量
PrecipitationSummary pastHour、past3Hours、past6Hours、past9Hours、past12Hours、past18Hours、past24Hours 过去 1、3、6、9、12、18、24 小时降水量
TemperatureSummary past6HourRange、past12HourRange、past24HourRange 过去 6、12、24 小时的温度区间

注意事项

  • hourlyLength 只能是 1–72，dailyLength 只能是 1–10。超出范围会返回参数错误。
  • 三个接口查询的都是单个经纬度，不表示沿路线的天气。沿路线风险见 Trip Weather。
  • 用完 SDK 后调用 WeatherService.dispose() 释放资源。

相关指南