天气预报国际版：5 分钟快速开始（注册到第一次全球天气查询）
# 天气预报国际版：5 分钟快速开始（注册到第一次全球天气查询）
> 接口：天气预报国际版（apiCode=3540）· 免费接口 · POST/GET · JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 6 分钟
## 核心要点
- 天气预报国际版提供全球数百万个地点的**当前天气（3540-1）、24 小时预报（3540-2）、14 天预报（3540-3）**三个接入点，注册后默认可免费调用。
- 只需一个 AppKey + 一种定位方式（城市名或经纬度），一次 HTTP 请求即可拿到结构化 JSON 天气数据。
- 本文代码已通过真实接口实测：复制、替换 `YOUR_APPKEY`，即可直接运行。
## Why
做出行类应用要展示目的地天气，做内容平台要给文章配城市天气，做 AI 助手要让用户问"伦敦现在多少度"——这些需求的第一步都一样：稳定拿到一份全球可用的天气 JSON。
天气预报国际版（apiCode=3540）是易源官方自营的免费接口：注册后默认即可免费调用（为防滥用设有使用档次限制，详见官方档位说明）。它覆盖全球数百万个地点，三个接入点分别解决"现在怎么样""今天剩下的时间怎么样""未来两周怎么样"三类问题。
本文带你走完从注册到拿到第一份天气数据的完整流程，全部代码经过真实接口实测。
## What
前置条件：
1. 已注册易源账号；
2. 在 [AppKey 管理控制台](https://www.showapi.com/console#/myApp) 拿到你的 AppKey；
3. 任一可发 HTTP 请求的环境（本文用 Python / cURL / Node.js）。
接口速览：
| 项目 | 说明 |
|------|------|
| 接入点 1 | `https://route.showapi.com/3540-1` 查询当前天气（含空气质量） |
| 接入点 2 | `https://route.showapi.com/3540-2` 查询24小时预报 |
| 接入点 3 | `https://route.showapi.com/3540-3` 查询14天预报 |
| 请求方式 | POST / GET |
| 返回格式 | JSON |
| 定位参数 | `name`（城市名）或 `lon` + `lat`（经纬度），二选一 |
| 鉴权 | URL 参数 `appKey=你的AppKey` |
| 计费 | 免费接口，设防滥用档次限制（以官方档位说明为准） |
| 集成能力 | MCP、OpenAPI 3.0（YAML/JSON）、多语言示例页 |
## How
### 1. 拿到 AppKey
登录后打开 [AppKey 管理控制台](https://www.showapi.com/console#/myApp)，复制你的 AppKey。本文所有代码中的 `YOUR_APPKEY` 都替换成它。
### 2. 第一次调用：查伦敦当前天气
Python（requests）：
```python
# pip install requests
import requests
APPKEY = "YOUR_APPKEY" # 在 https://www.showapi.com/console#/myApp 获取
url = "https://route.showapi.com/3540-1" # 3540-1 当前天气
resp = requests.post(
url,
params={"appKey": APPKEY, "name": "London"},
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')} (ret_code={body.get('ret_code')})")
info, now = body["cityInfo"], body["now"]
print(f'{info["city"]}({info["city_en"]}) 当前 {now["temperature"]}℃，{now["weather"]}，湿度 {now["humidity"]}%')
# 实测输出示例: 伦敦(London) 当前 18.9℃，阴天，湿度 83%
```
cURL：
```bash
curl -X POST "https://route.showapi.com/3540-1?appKey=YOUR_APPKEY&name=London"
```
Node.js（fetch）：
```js
const APPKEY = "YOUR_APPKEY";
const res = await fetch(
`https://route.showapi.com/3540-1?appKey=${APPKEY}&name=London`,
{ method: "POST" }
);
const data = await res.json();
if (data.showapi_res_code !== 0) throw new Error(data.showapi_res_error || "系统级错误");
const body = data.showapi_res_body;
if (body.ret_code !== 0) throw new Error(`${body.remark} (ret_code=${body.ret_code})`);
console.log(`${body.cityInfo.city} ${body.now.temperature}℃ ${body.now.weather}`);
```
### 3. 换一种定位方式：经纬度
城市名换成经纬度，只需替换参数（伦敦：`lon=-0.12574, lat=51.50853`）：
```python
resp = requests.post(url, params={"appKey": APPKEY, "lon": "-0.12574", "lat": "51.50853"}, timeout=10)
```
两种方式返回结构一致。定位参数的选择细节见[定位参数怎么传](https://www.showapi.com/guides/global-weather-location-params-3540)。
### 4. 换个接入点：24 小时与 14 天预报
把地址中的 `3540-1` 换成 `3540-2`（24 小时预报，返回 `hourList` 数组）或 `3540-3`（14 天预报，返回 `dayList` 数组），其余不变。两个接入点的字段解析见[24 小时预报实战](https://www.showapi.com/guides/global-weather-hourly-forecast-3540)与[14 天预报实战](https://www.showapi.com/guides/global-weather-14day-forecast-3540)。
## 返回示例与解析
实测（name=London，3540-1）关键返回：
```json
{
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"remark": "查询成功",
"ret_code": 0,
"cityInfo": {
"city": "伦敦", "city_en": "London",
"country": "United Kingdom", "country_code": "GB",
"time_zone": "Europe/London", "localtime": "2026-09-03 08:46:01",
"longitude": -0.12574, "latitude": 51.50853
},
"now": {
"temperature": 18.9, "feels_like": 17.6, "humidity": 83,
"weather": "阴天", "weather_en": "Overcast",
"wind_speed": 4.7, "wind_direction": "西南偏西",
"rain_prop": 24, "visibility": 10
}
}
}
```
- `showapi_res_code`：系统级状态，0 为成功；
- `showapi_fee_num`：本次计费次数（成功调用为 1，实测失败调用为 0，不扣次）；
- `cityInfo.city` 实测返回**中文城市名**，`city_en` 为英文名；
- `now` 内是当前天气正文，字段逐一解读见[返回字段全解](https://www.showapi.com/guides/global-weather-response-fields-3540)。
## 进阶与边界
- **失败不扣次**：实测不传定位参数时返回 `ret_code=-1`、`remark="经纬度不能为空"`，且 `showapi_fee_num=0`——参数调试阶段不用担心白白消耗调用次数。
- **城市名注意**：`name` 支持英文，中文支持较少（文档原话），实测"北京""伦敦"等主流城市可直接用中文；拿不准就用英文城市名或经纬度。
- **正式上线前**：建议为天气数据加一层缓存，具体见[免费档位下的缓存策略设计](https://www.showapi.com/guides/global-weather-cache-cost-3540)。
## FAQ
**Q1：没有 AppKey 能先试吗？**
不能。三个接入点都要求 `appKey` 参数，注册后在 [AppKey 管理控制台](https://www.showapi.com/console#/myApp)即可获取，免费接口注册后默认可调用。
**Q2：`name`、`lon`、`lat` 一个都不传会怎样？**
实测返回 `ret_code=-1`、`remark="经纬度不能为空"`，且 `showapi_fee_num=0` 不扣次。所以至少要传一种定位方式。
**Q3：免费额度具体有多少次？**
文档未给出具体次数，设有防滥用的使用档次限制，以官方免费接口档位说明页为准。
**Q4：返回的 `ret_code` 和 `showapi_res_code` 有什么区别？**
`showapi_res_code` 是系统级状态（0 成功）；`ret_code` 在 `showapi_res_body` 内，是业务级状态（0 成功）。两层都要判断，详见[返回字段全解](https://www.showapi.com/guides/global-weather-response-fields-3540)。
**Q5：`city` 字段返回的是中文还是英文？**
实测返回中文城市名（如"伦敦"），英文名在 `city_en` 字段。文档旧示例中该字段写作 `area`，以实际返回为准。
## 下一步阅读
- [天气预报国际版：定位参数怎么传（城市名 name 与经纬度 lon/lat 的选择）](https://www.showapi.com/guides/global-weather-location-params-3540)
- [天气预报国际版：返回字段全解（cityInfo / now / hourList / dayList 一文读懂）](https://www.showapi.com/guides/global-weather-response-fields-3540)
- [天气预报国际版：当前天气接入实战（气温、体感、风、降水概率全字段）](https://www.showapi.com/guides/global-weather-current-weather-3540)
- **本系列共 12 篇**：查看[天气预报国际版指南总目录](https://www.showapi.com/guides/global-weather-guides-3540)
