天气预报国际版：定位参数怎么传（城市名 name 与经纬度 lon/lat 的选择）
# 天气预报国际版：定位参数怎么传（城市名 name 与经纬度 lon/lat 的选择）
> 接口：天气预报国际版（apiCode=3540，全部接入点）· 免费接口 · POST/GET · JSON · 适用人群：初级及以上开发者 · 阅读时间：约 6 分钟
## 核心要点
- 三个接入点共用同一套定位参数：城市名 `name`，或经纬度 `lon` + `lat`，**二选一即可**，返回结构一致。
- 文档将三个参数都标为"选填"，但实测**一个都不传会失败**：`ret_code=-1`、`remark="经纬度不能为空"`（不扣次）。
- `name` 支持英文，中文支持较少；实测"北京""伦敦"等主流城市中文可直接命中，解析失败的城市名会落到同一个"经纬度不能为空"错误。
## Why
天气接口的第一个坑往往不在天气本身，而在"怎么告诉接口你要查哪里"。天气预报国际版给了两条路：直接给城市名，或给经纬度坐标。选错方式或传错值，轻则查不到城市，重则用户端定位飘到另一个国家。
本文把两种定位方式的适用边界、实测行为（含失败时的真实返回）讲清楚，帮你一次选对。
## What
三个接入点（3540-1 当前天气 / 3540-2 24小时预报 / 3540-3 14天预报）的定位参数完全相同：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | String | 文档标"否" | 城市名称：支持英文、中文（较少） |
| `lon` | String | 文档标"否" | 经度，如 `-0.1062` |
| `lat` | String | 文档标"否" | 纬度，如 `51.5171` |
文档虽将三者标为"否"，但实测三者全不传时业务层直接失败（见下文实测），实际使用中**至少传一种定位方式**。
## How
### 1. 方式一：城市名 `name`
Python：
```python
import requests
APPKEY = "YOUR_APPKEY"
def get_current_by_name(name: str) -> dict:
"""用城市名查当前天气。"""
resp = requests.post(
"https://route.showapi.com/3540-1",
params={"appKey": APPKEY, "name": name},
timeout=10,
)
body = resp.json()["showapi_res_body"]
if body.get("ret_code") != 0:
# 实测：城市名解析失败也会返回 remark="经纬度不能为空", ret_code=-1
raise ValueError(f"查询失败: {body.get('remark')}")
return body
print(get_current_by_name("London")["cityInfo"]["city"]) # 实测输出: 伦敦
print(get_current_by_name("北京")["cityInfo"]["city_en"]) # 实测输出: Beijing
```
### 2. 方式二：经纬度 `lon` + `lat`
```python
def get_current_by_coord(lon: str, lat: str) -> dict:
"""用经纬度查当前天气。"""
resp = requests.post(
"https://route.showapi.com/3540-1",
params={"appKey": APPKEY, "lon": lon, "lat": lat},
timeout=10,
)
body = resp.json()["showapi_res_body"]
if body.get("ret_code") != 0:
raise ValueError(f"查询失败: {body.get('remark')}")
return body
# 伦敦坐标
info = get_current_by_coord("-0.12574", "51.50853")["cityInfo"]
print(info["city"], info["time_zone"]) # 实测输出: 伦敦 Europe/London
```
cURL：
```bash
# 城市名方式
curl -X POST "https://route.showapi.com/3540-1?appKey=YOUR_APPKEY&name=bangkok"
# 经纬度方式（东京坐标）
curl -X POST "https://route.showapi.com/3540-1?appKey=YOUR_APPKEY&lon=139.69&lat=35.69"
```
Node.js：
```js
async function getByCoord(lon, lat) {
const res = await fetch(
`https://route.showapi.com/3540-1?appKey=${process.env.APPKEY}&lon=${lon}&lat=${lat}`,
{ method: "POST" }
);
const body = (await res.json()).showapi_res_body;
if (body.ret_code !== 0) throw new Error(body.remark);
return body;
}
```
### 3. 怎么选：一张决策表
| 你的场景 | 建议方式 | 理由 |
|---------|---------|------|
| 用户搜索框输入城市名 | `name`（英文优先） | 直接承接输入；解析失败再引导用户 |
| App 拿到了设备 GPS | `lon` + `lat` | 精确到当前位置，无城市歧义（同名城市） |
| 目的地是国际小城市/村镇 | `lon` + `lat` | 小地名英文名解析不确定性更高，坐标最稳 |
| 已有城市库（含坐标） | `lon` + `lat` | 坐标是唯一标识，避免重名城市错配 |
| 只知道中文城市名 | 先试 `name` 传中文，失败换拼音/英文或坐标 | 文档注明中文支持较少，主流城市实测可用 |
## 返回示例与解析
定位成功与否，看 `cityInfo` 是否正常回填。实测（name=北京，3540-1）：
```json
{
"cityInfo": {
"city": "北京", "city_en": "Beijing",
"region": "Beijing", "country": "China", "country_code": "CN",
"time_zone": "Asia/Shanghai", "localtime": "2026-09-03 15:46:00",
"longitude": 116.39723, "latitude": 39.9075
},
"ret_code": 0
}
```
关键点：无论你用哪种方式定位，`cityInfo` 都会把接口解析出的**标准城市**回给你（含时区、坐标）。用它做日志与对账，能第一时间发现"解析到的城市和预期不符"的问题。
## 进阶与边界
- **实测失败行为（重要）**：实测两种情况返回完全相同——①三个定位参数全不传；②传入无法解析的城市名（如 `name=nonexistentcity12345`）。返回均为 `ret_code=-1`、`remark="经纬度不能为空"`、`showapi_fee_num=0`（不扣次）。也就是说 `name` 的内部实现是先解析成坐标，解析失败落到同一错误提示。**你的代码不能依赖 remark 文案区分失败原因**，应自行记录请求参数。
- **中文支持**：文档注明"支持英文、中文（较少）"。实测北京、伦敦等主流城市中文可命中；冷门地名建议优先英文或坐标。
- **重名城市**：城市名定位存在同名歧义的可能，对位置敏感的业务建议一律走经纬度。
- `name` 示例值文档给过"纽约""bangkok""曼哈顿"，均可作为联调测试输入。
## FAQ
**Q1：文档说三个参数都不必填，是不是真的可以都不传？**
实测不行：三个全不传返回 `ret_code=-1`、`remark="经纬度不能为空"`。文档的"否"指参数本身可选，但定位信息至少要有一种。
**Q2：中文城市名到底能不能用？**
能用于主流城市：实测"北京"正常返回且 `city` 字段回中文。但文档明确"中文（较少）"，冷门地名不保证，建议英文或坐标兜底。
**Q3：城市名写错了会返回专门的错误码吗？**
实测不会。无效城市名与不传参数返回同一结果（`ret_code=-1`，"经纬度不能为空"），且不扣次。接口文档未提供更细的错误码枚举，失败原因需结合你传入的参数自行排查。
**Q4：经纬度应该传多少位精度？**
文档示例为 4 位小数（`-0.1062`/`51.5171`），按此量级传即可；天气数据是城市/区域级的，无需更高精度。
**Q5：两个接入点之间的定位参数行为一致吗？**
一致。三个接入点共用同一套参数定义，本文实测在 3540-1 上完成，3540-2/3540-3 参数表相同。
## 下一步阅读
- [天气预报国际版：5 分钟快速开始（注册到第一次全球天气查询）](https://www.showapi.com/guides/global-weather-quickstart-3540)
- [天气预报国际版：返回字段全解（cityInfo / now / hourList / dayList 一文读懂）](https://www.showapi.com/guides/global-weather-response-fields-3540)
- [天气预报国际版：14 天预报接入实战（行程规划与日出日落、月相字段）](https://www.showapi.com/guides/global-weather-14day-forecast-3540)
- **本系列共 12 篇**：查看[天气预报国际版指南总目录](https://www.showapi.com/guides/global-weather-guides-3540)
