天气预报国际版：返回字段全解（cityInfo / now / hourList / dayList 一文读懂）
# 天气预报国际版：返回字段全解（cityInfo / now / hourList / dayList 一文读懂）
> 接口：天气预报国际版（apiCode=3540，全部接入点）· 免费接口 · POST/GET · JSON · 适用人群：所有接入开发者 · 阅读时间：约 9 分钟
## 核心要点
- 返回体分两层：系统级（`showapi_res_code` / `showapi_res_error` / `showapi_res_id` / `showapi_fee_num`）+ 业务级 `showapi_res_body`（内含 `ret_code`），两层都要判断。
- 三个接入点共用 `cityInfo` 城市信息块；差异块分别是 `now`（当前天气）、`hourList[]`（逐小时）、`dayList[]`（逐天）。
- 本文所有结构来自文档并经真实接口实测校验，含文档与实测不一致处的修正说明，可直接当字段字典收藏。
## Why
接入天气接口后，80% 的现场问题最后都落到"这个字段是什么单位""这个值为空正常吗""这个错误码什么意思"。与其每次翻文档，不如把三个接入点的返回结构一次读透。
本文是全系列的字段速查页：其他场景文章讲到具体字段时，都会指回这里。
## What
系统级返回结构（三个接入点一致，来自真实返回示例）：
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | Number | 系统级状态码，0 为成功 |
| `showapi_res_error` | String | 系统级错误信息，成功时为空字符串 |
| `showapi_res_id` | String | 本次请求 ID（排查问题时可提供给服务商） |
| `showapi_fee_num` | Number | 本次计费次数；实测成功调用为 1、失败调用为 0 |
| `showapi_res_body` | Object | 业务数据封装，下文所有业务字段都在其中 |
业务级：`showapi_res_body.ret_code`（0 为成功，其他失败）；`remark`（结果描述，如"查询成功"）。
## How
### 1. `cityInfo`：城市信息（三个接入点共有）
实测结构（name=London）：
| 字段 | 类型 | 实测示例 | 说明 |
|------|------|---------|------|
| `city` | String | `伦敦` | 城市名（实测返回中文） |
| `city_en` | String | `London` | 城市名（英文）；文档字段表未列出，实测存在 |
| `region` | String | `England` | 地区 |
| `country` | String | `United Kingdom` | 国家 |
| `country_code` | String | `GB` | 国家代码；文档字段表未列出，实测存在 |
| `time_zone` | String | `Europe/London` | 时区 |
| `localtime` | String | `2026-09-03 08:46:01` | 当地时间 |
| `longitude` / `latitude` | Number | `-0.12574` / `51.50853` | 解析出的坐标 |
> 需修正项：文档 3540-1 的字段表中城市字段写作 `area`，实测返回为 `city` + `city_en`。代码请以 `city`/`city_en` 为准。
### 2. `now`：当前天气（仅 3540-1）
| 字段 | 类型 | 单位/说明 |
|------|------|----------|
| `temperature` | Number | 气温（℃） |
| `feels_like` | Number | 体感温度（℃） |
| `windchill` | Number | 风寒指数 |
| `heat_index` | Number | 热指数 |
| `humidity` | Number | 湿度（%） |
| `pressure` | Number | 大气压 |
| `dew_point` | Number | 露点温度（℃） |
| `wind_speed` / `gust_speed` | Number | 持续风速 / 阵风风速（m/s） |
| `wind_direction` / `wind_direction_en` | String | 风向（中文 / 英文缩写，如"西南偏西"/`WSW`） |
| `weather` / `weather_en` | String | 天气现象（中文 / 英文，如"阴天"/`Overcast`） |
| `cloud` | Number | 云层覆盖率（%） |
| `rain_prop` / `snow_prob` | Number | 下雨概率 / 下雪概率 |
| `visibility` | Number | 能见度（km） |
| `uv` | Number | 紫外线指数 |
| `air_quality` | Object | 空气质量，详见[空气质量实战](https://www.showapi.com/guides/global-weather-air-quality-3540) |
| `short_rad` / `diff_rad` / `dni` / `gti` | Number | 辐射类字段（W/m²），详见[辐射与 UV 解读](https://www.showapi.com/guides/global-weather-radiation-uv-3540) |
### 3. `hourList`：24 小时预报（仅 3540-2）
数组，每项为一小时，字段与 `now` 高度一致（不含 `air_quality`），另有：
| 字段 | 类型 | 说明 |
|------|------|------|
| `time` | String | 小时时间（**当地时间**，如 `2026-09-03 14:00`） |
| `snow` | Number | 降雪量 |
解析代码：
```python
for h in body["hourList"]:
print(h["time"], f'{h["temperature"]}℃', h["weather"], f'降雨概率{h["rain_prop"]}%')
```
### 4. `dayList`：14 天预报（仅 3540-3）
数组，每项为一天：
| 字段 | 类型 | 说明 |
|------|------|------|
| `date` | String | 日期（`2026-09-03`） |
| `temperature` | Number | 平均气温 |
| `max_temperature` / `min_temperature` | Number | 最高 / 最低气温 |
| `humidity` | Number | 湿度（%） |
| `rain_prop` / `snow_prob` | Number | 降雨概率 / 降雪概率 |
| `total_precip` / `total_snow` | Number | 总降水量（mm）/ 总降雪量（cm） |
| `max_wind_speed` | Number | 最大风速 |
| `visibility` / `uv` | Number | 能见度 / 紫外线指数 |
| `weather` / `weather_en` | String | 天气现象（中/英） |
| `sunrise` / `sunset` | String | 日出 / 日落时间 |
| `moon_phase` / `moon_phase_en` | String | 月相（中/英，如"下弦月"/`Last Quarter`） |
| `moonrise` / `moonset` | String | 月出 / 月落时间（实测可能有例外，见下） |
| `moon_illumination` | Number | 月光亮度（% 实测取值 0~100 区间的数值） |
cURL 快速验证：
```bash
curl -X POST "https://route.showapi.com/3540-3?appKey=YOUR_APPKEY&name=bangkok"
```
## 进阶与边界
- **`moonrise` 容错（实测）**：当天的月相"不出"时，`moonrise` 返回字符串 `Does not rise today` 而非时间。解析时先判断是否为时间格式。
- **`dni`/`gti` 实测观察**：实测多个白天时段 `dni` 与 `gti` 返回 0，`short_rad`/`diff_rad` 正常（如曼谷正午 `short_rad=938.38`）。文档对 `dni` 的中文描述在 3540-1（"散射辐射"）与 3540-2（"直接辐射"）两处不一致；使用辐射类字段前建议业务侧实测验证，勿直接用于光伏发电量等严肃计算。
- **`air_quality` 只在当前天气返回**：24 小时与 14 天预报的返回中没有空气质量块。
- **天气现象无官方枚举表**：实测样例有 晴天/Sunny、阴天/Overcast、多云/Cloudy、局部多云/Partly Cloudy、附近局部降雨/Patchy rain nearby、小阵雨/Light rain shower。界面映射时以实际返回为准，未收录现象给出兜底展示。
- **空值处理**：文档字段表中部分字段示例值为"-"，实际返回可能缺失，取值时统一判空。
## FAQ
**Q1：判断调用成功到底看哪个字段？**
两层都看：`showapi_res_code == 0` 且 `showapi_res_body.ret_code == 0`。任一非 0 都按失败处理，取 `showapi_res_error` 或 `remark` 做日志。
**Q2：`ret_code` 有哪些错误码枚举？**
接口文档未提供完整枚举，本文不编造。实测到的是：`ret_code=-1`、`remark="经纬度不能为空"`（定位信息缺失或城市名解析失败时）。
**Q3：为什么我拿到的城市字段是 `city` 而文档写的是 `area`？**
以实测为准：实际返回为 `city`（中文）与 `city_en`（英文）。文档该处表述与实际返回存在出入。
**Q4：`hourList` 的 `time` 是北京时间吗？**
不是，是查询目标地的**当地时间**（配合 `cityInfo.time_zone` 使用）。展示逐时曲线时注意时区换算。
**Q5：`showapi_fee_num=0` 是不是没扣费？**
实测是：失败的调用（如缺定位参数）返回 `showapi_fee_num=0`，不扣次；成功调用为 1。
**Q6：14 天预报一定返回 14 条吗？**
文档定位为"未来 14 天预报"，实测返回按天排列的 `dayList` 数组；个别字段（如 `total_precip`）可能缺失，代码判空即可，不要对数组长度做硬断言。
## 下一步阅读
- [天气预报国际版：当前天气接入实战（气温、体感、风、降水概率全字段）](https://www.showapi.com/guides/global-weather-current-weather-3540)
- [天气预报国际版：空气质量数据接入实战（AQI 与六项污染物指标）](https://www.showapi.com/guides/global-weather-air-quality-3540)
- [天气预报国际版：太阳辐射与紫外线字段解读（short_rad / dni / gti / uv）](https://www.showapi.com/guides/global-weather-radiation-uv-3540)
- **本系列共 12 篇**：查看[天气预报国际版指南总目录](https://www.showapi.com/guides/global-weather-guides-3540)
