天气预报国际版：当前天气接入实战（气温、体感、风、降水概率全字段）
# 天气预报国际版：当前天气接入实战（气温、体感、风、降水概率全字段）
> 接口：天气预报国际版（apiCode=3540）接入点 1 查询当前天气 · 免费接口 · POST/GET · JSON · 适用人群：前端/全栈工程师、产品经理 · 阅读时间：约 7 分钟
## 核心要点
- 接入点 `3540-1` 是三个接入点里信息最全的：唯一返回 `air_quality` 空气质量块的接入点，`now` 对象一次给齐温、湿、风、降水概率、能见度、UV。
- 体感类字段有三个（`feels_like` / `windchill` / `heat_index`），分别对应综合体感、风寒、炎热三种生理感受，不要混用。
- 本文示例全部经真实接口实测（北京、伦敦双城市验证），可直接运行。
## Why
"现在外面什么天气"是天气类需求里调用量最大、位置最靠前的一块：App 首页卡片、小程序顶部横幅、企业微信机器人早报、AI 助手的即时回答，底层都是同一个动作——查当前天气。
天气预报国际版的当前天气接入点把当前实况做成了一个大而全的 `now` 对象，还附带了多数免费天气接口不提供的太阳辐射组字段。本文带你把它逐字段吃透，并给出可直接复用的天气卡片代码。
## What
| 项目 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/3540-1?appKey={your_appKey}` |
| 接入点 | [查询当前天气（3540-1）](https://www.showapi.com/apiGateway/view/3540/1) |
| 请求方式 | POST / GET，返回 JSON |
| 定位参数 | `name` 或 `lon`+`lat`（二选一，详见[定位参数](https://www.showapi.com/guides/global-weather-location-params-3540)） |
| 计费 | 免费接口（防滥用档次限制，以官方档位说明为准） |
| 特色 | 全系唯一含 `air_quality` 的接入点；含辐射组字段 |
## How
### 1. 拉取并整理当前天气
Python：
```python
# pip install requests
import requests
APPKEY = "YOUR_APPKEY"
def fetch_current(name=None, lon=None, lat=None) -> dict:
"""查询当前天气，返回标准化后的字典。"""
params = {"appKey": APPKEY}
if lon and lat:
params.update({"lon": lon, "lat": lat})
elif name:
params["name"] = name
else:
raise ValueError("必须提供城市名或经纬度") # 实测：全不传会 ret_code=-1
resp = requests.post("https://route.showapi.com/3540-1",
params=params, timeout=10)
data = resp.json()
if data["showapi_res_code"] != 0:
raise RuntimeError(f"系统级错误: {data.get('showapi_res_error')}")
body = data["showapi_res_body"]
if body.get("ret_code") != 0:
raise RuntimeError(f"业务错误: {body.get('remark')}")
now, info = body["now"], body["cityInfo"]
return {
"city": info.get("city"), # 实测为中文名，如"伦敦"
"city_en": info.get("city_en"),
"localtime": info.get("localtime"), # 当地时间
"temp": now.get("temperature"),
"feels": now.get("feels_like"),
"weather": now.get("weather"),
"weather_en": now.get("weather_en"),
"humidity": now.get("humidity"),
"wind": f'{now.get("wind_direction")}/{now.get("wind_speed")}m/s',
"rain_prop": now.get("rain_prop"), # 下雨概率(%)
"visibility": now.get("visibility"), # 能见度(km)
"uv": now.get("uv"),
}
card = fetch_current(name="北京")
print(card)
# 实测输出: {'city': '北京', 'temp': 33.7, 'weather': '晴天', 'humidity': 23, ...}
```
cURL：
```bash
curl -X POST "https://route.showapi.com/3540-1?appKey=YOUR_APPKEY&name=北京"
```
Node.js：
```js
const res = await fetch(
`https://route.showapi.com/3540-1?appKey=${process.env.APPKEY}&name=${encodeURIComponent("北京")}`,
{ method: "POST" }
);
const { showapi_res_body: body } = await res.json();
if (body.ret_code !== 0) throw new Error(body.remark);
const { city, now } = body;
console.log(`${city} ${now.temperature}℃ ${now.weather} 体感${now.feels_like}℃`);
```
### 2. 渲染成天气卡片（前端片段）
```html
<div class="weather-card">
<span class="city">{{ city }}（{{ city_en }}）</span>
<span class="temp">{{ temp }}℃</span>
<span class="desc">{{ weather }}</span>
<span class="meta">体感 {{ feels }}℃ · 湿度 {{ humidity }}% · {{ wind }}</span>
<span class="meta" v-if="rain_prop >= 40">☔ 降雨概率 {{ rain_prop }}%，记得带伞</span>
</div>
```
### 3. 三个"体感"字段怎么用
| 字段 | 含义 | 使用建议 |
|------|------|---------|
| `feels_like` | 综合体感温度 | 默认展示用这个 |
| `windchill` | 风寒指数（低温+风环境的"冷感"） | 冬季/低温场景提示 |
| `heat_index` | 热指数（高温+湿度的"热感"） | 夏季高温预警提示 |
实测（北京晴天 33.7℃）：`feels_like=31.9`、`windchill=33.7`、`heat_index=32.1`。三者数值接近但不相同，业务上各取所需。
## 返回示例与解析
实测关键返回（name=北京）：
```json
{
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"remark": "查询成功",
"ret_code": 0,
"cityInfo": { "city": "北京", "city_en": "Beijing", "time_zone": "Asia/Shanghai", "localtime": "2026-09-03 15:46:00" },
"now": {
"temperature": 33.7, "feels_like": 31.9, "windchill": 33.7, "heat_index": 32.1,
"humidity": 23, "pressure": 1014, "dew_point": 9.5,
"wind_direction": "东南偏南", "wind_direction_en": "SSE", "wind_speed": 2.5, "gust_speed": 6.5,
"weather": "晴天", "weather_en": "Sunny", "cloud": 0,
"rain_prop": 0, "snow_prob": 0, "visibility": 10, "uv": 3.3,
"air_quality": { "aqi": 500, "primary_pollutant": "co", "pm2_5": 25.1, "pm10": 26 }
}
}
}
```
字段级完整说明见[返回字段全解](https://www.showapi.com/guides/global-weather-response-fields-3540)。
## 进阶与边界
- **空气质量实测观察**：本文与文档示例中多城市实测 `aqi` 均为 500（`primary_pollutant=co`）。各分项污染物数值随城市变化，但 `aqi` 数值建议在业务侧做合理性校验（或与当地站点数据交叉验证）后再展示给用户。
- **辐射字段慎用于严肃场景**：`short_rad`/`diff_rad` 实测正常，但 `dni`/`gti` 在多个白天实测为 0（详见[辐射与 UV 解读](https://www.showapi.com/guides/global-weather-radiation-uv-3540)）。
- **天气现象做映射**：`weather` 中文文案实测有"晴天/阴天/多云/局部多云/附近局部降雨/小阵雨"等，无官方枚举表，图标映射记得留兜底。
- **别忘了当地时间**：`cityInfo.localtime` 是目标城市当地的时间，跨时区展示时以它为准而不是服务器时间。
## FAQ
**Q1：当前天气多久更新一次？**
接口文档未标注更新频率，本文不做无依据的断言。对实时性要求高的场景建议自行抽样对比验证更新节奏。
**Q2：能只查温度不要其他字段吗？**
不能裁剪返回，但你可以按需取字段。若调用量敏感，配合缓存使用（见[缓存策略设计](https://www.showapi.com/guides/global-weather-cache-cost-3540)）。
**Q3：`rain_prop` 是百分比吗？**
是，实测取值如 24、0、4 等，表示下雨概率（%）。用它做"是否带伞"提示时建议设阈值（如 ≥40%）。
**Q4：为什么 `cloud` 有时是 0 有时是 91？**
`cloud` 是云层覆盖率（%），随实况变化。实测北京晴天为 0、伦敦阴天为 91，符合直觉。
**Q5：和 24 小时预报的第一个小时数据一样吗？**
数据源与含义不同：3540-1 是当前实况，3540-2 是逐时预报（首小时 `time` 为整点）。展示"现在"用 3540-1，展示"接下来几小时"用 3540-2。
## 下一步阅读
- [天气预报国际版：空气质量数据接入实战（AQI 与六项污染物指标）](https://www.showapi.com/guides/global-weather-air-quality-3540)
- [天气预报国际版：24 小时预报接入实战（逐小时天气卡片与出行提醒）](https://www.showapi.com/guides/global-weather-hourly-forecast-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)
