坐标系转换：5 分钟接入，从第一条 WGS84→GCJ02 结果开始
# 坐标系转换：5 分钟接入，从第一条 WGS84→GCJ02 结果开始
> 接口：坐标系转换（apiCode=1252，接入点 1「坐标系转换」）· 免费 · 请求方式 POST/GET · 返回 JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 5 分钟
## TL;DR
- 坐标系转换支持 WGS84 / GCJ02（火星坐标系）/ BD09（百度坐标系）三者**互相转换**，免费、注册即可调用。
- 一次调用只需 3 个必填参数：`from`、`to`、`location`（经纬度，最多 20 个点）。
- 返回 `resultList` 里每个点的 `output` 就是转换后的坐标（数组，下标 0=经度、1=纬度）。
## Why
你在做地图、定位、轨迹、外卖/出行类功能时，几乎一定会遇到"坐标对不上"的问题：手机 GPS 拿到的是 WGS84，但高德、腾讯地图用的是 GCJ02，百度用的是 BD09。直接把 GPS 坐标往高德上打点，点位会偏移几百米。坐标系转换接口就是把这个"翻译"过程变成一行 API 调用。
本篇目标：让你在 5 分钟内拿到第一个真实可用的转换结果，跑通后其他场景只是换参数。
## What
前置条件：
- 已注册 ShowAPI 账号，并获取 AppKey（[AppKey 管理](https://www.showapi.com/console#/myApp)）。
- 本接口为**免费服务**，注册后默认可调用，设有使用档位限制（可用积分兑换更高档位），具体档位以[官方档位说明](https://www.showapi.com/island/free-api)为准。
接口速览：
| 项 | 值 |
|----|----|
| 接口 / 接入点 | 坐标系转换 · apiCode=1252 · 接入点 1 |
| 接口地址 | `https://route.showapi.com/1252-1?appKey={your_appKey}` |
| 请求方式 | POST / GET |
| 鉴权 | URL query 参数 `appKey` |
| 返回格式 | JSON |
| 更新频率 | 每次查询都返回最新数据（无状态实时计算） |
| 集成能力 | MCP（`showapi-mcp-1252`）、OpenAPI 3.0（`/openapi/market/1252.yaml`） |
## How
以"把 GPS 的 WGS84 坐标 `113.194329,23.234704` 转成高德/腾讯用的 GCJ02"为例。
**步骤 1：准备 AppKey**，替换下面代码里的 `YOUR_APPKEY`。
**步骤 2：发起转换请求**，三个必填参数：
- `from`：源坐标系，取值 `WGS84` / `GCJ02` / `BD09`
- `to`：目标坐标系，取值同上
- `location`：源坐标，格式 `经度,纬度`，多个点用 `;` 隔开，**最多 20 个**
### Python（requests）
```python
import requests
app_key = "YOUR_APPKEY"
url = "https://route.showapi.com/1252-1"
params = {"appKey": app_key}
data = {
"from": "WGS84",
"to": "GCJ02",
"location": "113.194329,23.234704",
}
try:
resp = requests.post(url, params=params, data=data, timeout=10)
resp.raise_for_status()
body = resp.json().get("showapi_res_body", {})
if body.get("ret_code") != 0:
print("业务失败：", body)
else:
for item in body.get("resultList", []):
print("输入:", item["input"], "→ 输出:", item["output"])
except Exception as e:
print("请求异常:", e)
```
### cURL
```bash
curl -X POST "https://route.showapi.com/1252-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "from=WGS84&to=GCJ02&location=113.194329%2C23.234704"
```
### Node.js（fetch）
```javascript
const appKey = "YOUR_APPKEY";
const url = `https://route.showapi.com/1252-1?appKey=${appKey}`;
const body = new URLSearchParams({ from: "WGS84", to: "GCJ02", location: "113.194329,23.234704" });
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 10000);
try {
const resp = await fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body, signal: controller.signal,
});
const json = await resp.json();
const res = json.showapi_res_body;
if (res.ret_code !== 0) { console.log("业务失败：", res); }
else { res.resultList.forEach(it => console.log("输入:", it.input, "→ 输出:", it.output)); }
} catch (e) { console.log("请求异常:", e); }
finally { clearTimeout(timer); }
```
**步骤 3：看输出**。`output` 即为转换后的 GCJ02 坐标。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"to": "GCJ02",
"ret_code": 0,
"resultList": [
{ "input": [113.194329, 23.234704], "output": [113.19971018888167, 23.232115136208677] }
],
"from": "WGS84"
}
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_body.from` | String | 源坐标系名称 |
| `showapi_res_body.to` | String | 目标坐标系名称 |
| `showapi_res_body.resultList[]` | Object[] | 转换结果列表 |
| `resultList[].input` | 数组 | 输入点，下标 0=经度、1=纬度 |
| `resultList[].output` | 数组 | 转换后点，下标 0=经度、1=纬度 |
| `showapi_res_body.ret_code` | Number | 业务成功标识（示例为 0） |
> 注：文档参数表中 `input`/`output` 类型标注为 String，但描述与返回示例均为**数组**，以数组为准。
## 进阶 / 边界
- **最多 20 个点**：单次请求 `location` 最多带 20 个坐标，超出需分批（见[坐标系转换（批量）：一次性转换最多 20 个 GPS 点位](https://www.showapi.com/guides/coord-convert-batch-1252)）。
- **经纬度范围**：经度 -180~180，纬度 -90~90，**经度在前、纬度在后**。
- **免费但有档位**：突发大调用量建议做本地缓存（见[免费接口的成本管控：坐标系转换的本地缓存与批量合并策略](https://www.showapi.com/guides/coord-convert-cache-1252)）。
## FAQ
**Q1：这个接口真的免费吗？**
A：是免费服务，注册后默认可调用，但设有使用档位限制（防滥用），可用平台积分兑换更高调用档位；具体档位以[官方档位说明](https://www.showapi.com/island/free-api)为准。
**Q2：AppKey 在哪获取？**
A：登录后到[AppKey 管理](https://www.showapi.com/console#/myApp)创建并复制，替换代码里的 `YOUR_APPKEY`。
**Q3：一次能转换几个点？**
A：接入点 1 单次请求最多 20 个点，用 `;` 分隔。
**Q4：经纬度顺序写反了会怎样？**
A：接口按"经度,纬度"解析，写反会导致坐标落在错误位置；务必经度在前。
**Q5：返回里 `ret_code` 不是 0 怎么办？**
A：文档仅给出成功样例（ret_code=0），未枚举失败错误码；出现非 0 时以实际返回内容为准排查（多为参数取值/格式问题）。
## 相关能力 / 下一步阅读
- [坐标系转换：返回结构与 ret_code 全解（含批量 resultList 字段）](https://www.showapi.com/guides/coord-convert-response-1252)
- [WGS84 / GCJ02（火星坐标）/ BD09 到底是什么？为什么必须转换？](https://www.showapi.com/guides/coord-convert-concepts-1252)
- [高德/腾讯/百度/Google 地图坐标互通：坐标系转换在地图集成中的全链路设计](https://www.showapi.com/guides/coord-convert-map-platform-1252)
- **本系列共 12 篇**：查看[坐标系转换指南总目录](https://www.showapi.com/guides/coord-convert-guides-1252)
