天气预报国际版：太阳辐射与紫外线字段解读（short_rad / dni / gti / uv）
# 天气预报国际版：太阳辐射与紫外线字段解读（short_rad / dni / gti / uv）
> 接口：天气预报国际版（apiCode=3540）接入点 1 / 2 · 免费接口 · POST/GET · JSON · 适用人群：户外/能源/健康类应用开发者 · 阅读时间：约 6 分钟
## 核心要点
- 当前天气与逐小时预报都带一组少见的**太阳辐射字段**：`short_rad`（短波/全球水平辐射）、`diff_rad`（水平面散射）、`dni`、`gti`（倾角辐射），单位 W/m²，外加紫外线指数 `uv`。
- 实测观察：白天多个时段 `dni` 与 `gti` 返回 0，而 `short_rad`/`diff_rad` 数值正常（曼谷正午 `short_rad=938.38`）；文档对 `dni` 的中文描述在两处接入点还不一致。
- 本文如实呈现字段定义与实测现象，辐射字段可用于展示与参考场景，用于光伏等严肃计算前务必业务侧实测验证。
## Why
紫外线提醒（防晒）、光伏发电参考、户外运动强度评估——这些场景要看的不是"晴天还是多云"，而是太阳辐射本身。多数天气接口只给 UV 指数，天气预报国际版额外暴露了 4 个辐射字段，这在免费天气接口里不多见。
不过，字段多也意味着理解成本高：四个辐射字段什么关系？单位是什么？数据可靠性如何？本文基于文档定义 + 真实接口实测，把这些问题讲透。
## What
字段速查（均见于 3540-1 的 `now` 与 3540-2 的 `hourList[]`；3540-3 日级只有 `uv`）：
| 字段 | 单位 | 文档描述 | 说明 |
|------|------|---------|------|
| `uv` | - | 紫外线指数 | 通用 UV 指数，白天高、夜间为 0，实测曼谷午后 9.4 |
| `short_rad` | W/m² | 短波太阳辐射或全球水平辐射 | 即气象上的 GHI（全球水平辐照）口径 |
| `diff_rad` | W/m² | 水平面散射日射量 | 散射部分 |
| `dni` | W/m² | 3540-1 写"散射辐射"，3540-2 写"直接辐射" | DNI 气象惯例为**直接法向辐照**；两处描述不一致 |
| `gti` | W/m² | 倾角辐射 | 倾斜面辐照，光伏组件面口径 |
> `uv` 与 `dni`/`gti` 等在文档字段表中部分示例值为"-"，实际返回可能缺失，取值判空。
## How
### 1. 拉取并展示 UV 与辐射
Python：
```python
# pip install requests
import requests
APPKEY = "YOUR_APPKEY"
def fetch_uv_rad(city: str) -> dict:
resp = requests.post(
"https://route.showapi.com/3540-1",
params={"appKey": APPKEY, "name": city},
timeout=10,
)
body = resp.json()["showapi_res_body"]
if body.get("ret_code") != 0:
raise RuntimeError(f"业务错误: {body.get('remark')}")
now = body["now"]
return {
"city": body["cityInfo"]["city"],
"uv": now.get("uv"),
"short_rad": now.get("short_rad"),
"diff_rad": now.get("diff_rad"),
"dni": now.get("dni"),
"gti": now.get("gti"),
}
def uv_tip(uv):
if uv is None: return "暂无数据"
if uv < 3: return "弱，无需特别防护"
if uv < 6: return "中等，出门建议防晒"
if uv < 8: return "强，遮阳帽+防晒霜"
if uv < 11: return "很强，避免正午暴晒"
return "极强，尽量不外出"
r = fetch_uv_rad("bangkok")
print(f'{r["city"]} UV={r["uv"]} -> {uv_tip(r["uv"])}；短波辐射 {r["short_rad"]} W/m²')
# 实测输出示例: 曼谷 UV=9.4 -> 很强，避免正午暴晒；短波辐射 938.38 W/m²
```
cURL：
```bash
curl -X POST "https://route.showapi.com/3540-1?appKey=YOUR_APPKEY&name=bangkok"
```
Node.js（逐小时 UV 峰值）：
```js
const res = await fetch(
`https://route.showapi.com/3540-2?appKey=${process.env.APPKEY}&name=bangkok`,
{ method: "POST" }
);
const body = (await res.json()).showapi_res_body;
const peak = body.hourList.reduce((a, b) => ((b.uv ?? -1) > (a.uv ?? -1) ? b : a));
console.log(`今日 UV 峰值出现在 ${peak.time}，uv=${peak.uv}`);
```
### 2. 防晒提醒的推荐组合
用逐小时 `uv` 找峰值时段 + 当前天气的 `uv` 做即时提示，比单一时刻值更实用；`uv_tip` 分级为 UV 指数通用分级常识，按业务口径调整。
## 返回示例与解析
实测（name=bangkok，3540-2，14 时）：
```json
{
"time": "2026-09-03 14:00",
"uv": 9.4,
"short_rad": 938.38,
"diff_rad": 84.74,
"dni": 0,
"gti": 0,
"cloud": 85
}
```
实测（name=北京，3540-1，15 时）：`uv=3.3, short_rad=689.78, diff_rad=98.84, dni=0, gti=0, cloud=0`。
两个城市的 `short_rad`/`diff_rad` 都有正常量级，而 `dni`/`gti` 均为 0——这就是下文"进阶与边界"要重点说的实测观察。
## 进阶与边界
- **`dni`/`gti` 实测为 0（重要观察）**：本文在北京（晴，cloud=0）、曼谷（多云，cloud=85）白天时段实测，`dni` 与 `gti` 均返回 0，而 `short_rad`/`diff_rad` 正常。可能的原因（推断，未经官方确认）：数据源未提供该两项、或按当地条件计算为 0。**建议**：展示类场景可如实展示；光伏发电量估算等严肃场景，先做长周期实测对比，勿直接依赖。
- **`dni` 的中文描述不一致**：3540-1 文档表写"散射辐射"，3540-2 写"直接辐射"。气象惯例 DNI = Direct Normal Irradiance（直接法向辐照），"散射"的表述与惯例不符，以官方最终解释为准。
- **`uv` 是最稳的一个**：实测昼夜变化规律（曼谷 14 时 9.4 → 17 时 0.4 → 夜间 0），用于防晒提醒可靠。
- **判空**：辐射字段实测偶有缺失（文档示例值"-"），统一判空。
## FAQ
**Q1：四个辐射字段怎么区分？**
`short_rad`（全球水平）、`diff_rad`（其中散射部分）、`dni`（直接法向）、`gti`（倾斜面）。做光伏参考关注 `gti`/`dni`，做"太阳晒不晒"的直觉展示关注 `short_rad` + `uv`。
**Q2：`dni` 一直是 0，是不是我调用姿势不对？**
与调用方式无关：本文用不同城市、不同天气条件实测均为 0，`short_rad` 同时刻正常。属于数据侧现象，见"进阶与边界"。
**Q3：`uv` 晚上是 0 正常吗？**
正常。紫外线随日照存在，实测曼谷夜间 `uv=0`、午后 `uv=9.4`。
**Q4：`short_rad` 单位一定是 W/m² 吗？**
是，文档字段说明标注 W/m²，实测量级（数百）也符合该单位的白天特征。
**Q5：14 天预报里有辐射字段吗？**
日级 `dayList` 只有 `uv`，没有四个辐射字段；需要辐射请用 3540-1（当前）或 3540-2（逐时）。
## 下一步阅读
- [天气预报国际版：24 小时预报接入实战（逐小时天气卡片与出行提醒）](https://www.showapi.com/guides/global-weather-hourly-forecast-3540)
- [天气预报国际版：当前天气接入实战（气温、体感、风、降水概率全字段）](https://www.showapi.com/guides/global-weather-current-weather-3540)
- [天气预报国际版：返回字段全解（cityInfo / now / hourList / dayList 一文读懂）](https://www.showapi.com/guides/global-weather-response-fields-3540)
- **本系列共 12 篇**：查看[天气预报国际版指南总目录](https://www.showapi.com/guides/global-weather-guides-3540)
