坐标系转换：返回结构与 ret_code 全解（含批量 resultList 字段）
坐标系转换返回结构ret_coderesultList字段解析 # 坐标系转换：返回结构与 ret_code 全解（含批量 resultList 字段）
> 接口：坐标系转换（apiCode=1252，接入点 1「坐标系转换」）· 免费 · 返回 JSON · 适用人群：初级~中级开发者 · 阅读时间：约 6 分钟
## TL;DR
- 业务数据全部包在 `showapi_res_body` 里；系统级字段 `showapi_res_code` 表示整次请求成功与否。
- 接入点 1 的核心返回是 `resultList[]`，每个元素含 `input`（原坐标）与 `output`（转换后坐标），均为**数组**（下标 0=经度、1=纬度）。
- `ret_code` 是业务成功标识；文档仅示例成功态 `0`，未枚举失败错误码，失败时以实际返回为准。
## Why
调用成功拿到 JSON 后，最怕两件事：① 不知道哪个字段才是真正的坐标；② 把 `input`/`output` 当成字符串去拆分，结果解析报错。本篇把返回结构彻底讲清，让你一次写对解析代码，不再被嵌套字段绕晕。
## What
前置条件：已能成功调用接口（见[坐标系转换：5 分钟接入](https://www.showapi.com/guides/coord-convert-quickstart-1252)）。
返回结构速览（接入点 1）：
| 项 | 值 |
|----|----|
| 系统级封装 | `showapi_res_body`（业务数据均在此对象内） |
| 源/目标系名 | `from` / `to`（String） |
| 结果列表 | `resultList`（Object[]） |
| 单点输入 | `resultList[].input`（数组：[经度, 纬度]） |
| 单点输出 | `resultList[].output`（数组：[经度, 纬度]） |
| 业务标识 | `ret_code`（Number） |
## How
解析代码（以 Python 为例，重点在正确读取数组）：
```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;113.194329,23.234704", # 批量：最多 20 个，; 分隔
}
resp = requests.post(url, params=params, data=data, timeout=10)
body = resp.json()["showapi_res_body"]
print("源系:", body["from"], "→ 目标系:", body["to"], "ret_code:", body["ret_code"])
for item in body["resultList"]:
lng, lat = item["output"] # output 是数组 [经度, 纬度]
print(f"原坐标 {item['input']} → 转换后 {lng},{lat}")
```
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%3B113.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;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 res = (await resp.json()).showapi_res_body;
console.log("源系:", res.from, "→ 目标系:", res.to, "ret_code:", res.ret_code);
for (const it of res.resultList) {
const [lng, lat] = it.output;
console.log(`原坐标 ${it.input} → 转换后 ${lng},${lat}`);
}
} catch (e) { console.log("请求异常:", e); }
finally { clearTimeout(timer); }
```
## 返回示例与解析
```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] },
{ "input": [113.194329, 23.234704], "output": [113.19971018888167, 23.232115136208677] }
],
"from": "WGS84"
}
}
```
| 字段 | 类型（实测） | 说明 |
|------|------|------|
| `showapi_res_code` | Number | 系统级：整次请求状态，示例 `0` |
| `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，但描述写"数组，下标0为经度、下标1为纬度"，返回示例也是数组——**一律按数组解析**。
## 进阶 / 边界
- **批量返回**：`location` 传 N 个点，`resultList` 就有 N 个元素，顺序与输入一一对应，无需再匹配。
- **ret_code 失败态**：文档只示例成功（0），未给出失败枚举值；遇到非 0 时优先检查 `from`/`to` 取值（仅 WGS84/GCJ02/BD09）、`location` 格式与经纬度范围。
- **接入点 2 的结构更简单**：两点直线距离只返回 `distance`（米）与 `ret_code`，见[两点直线距离：如何计算两坐标间的真实公里数？](https://www.showapi.com/guides/coord-convert-distance-1252)。
## FAQ
**Q1：为什么 `input`/`output` 是数组不是字符串？**
A：文档参数表类型标注为 String，但描述与示例均为数组 `[经度, 纬度]`；以实际数组结构解析即可。
**Q2：`ret_code` 有哪些取值？**
A：文档仅给出成功样例 `0`，未枚举失败错误码；非 0 以实际返回为准，通常是参数取值/格式问题。
**Q3：批量时如何对应输入与输出？**
A：`resultList` 元素顺序与 `location` 中传入的点顺序一致，按下标对应即可。
**Q4：系统级 `showapi_res_code` 和业务 `ret_code` 有什么区别？**
A：`showapi_res_code` 是系统级（请求层面），`ret_code` 在 `showapi_res_body` 内是业务级；两者都为 0 表示完全成功。
**Q5：最多能返回多少个点？**
A：接入点 1 单次请求最多转换 20 个坐标点。
## 相关能力 / 下一步阅读
- [坐标系转换（批量）：一次性转换最多 20 个 GPS 点位](https://www.showapi.com/guides/coord-convert-batch-1252)
- [两点直线距离：如何计算两坐标间的真实公里数？](https://www.showapi.com/guides/coord-convert-distance-1252)
- [坐标系转换避坑：点位偏移 500 米、距离算错、坐标系混用](https://www.showapi.com/guides/coord-convert-pitfalls-1252)
- **本系列共 12 篇**：查看[坐标系转换指南总目录](https://www.showapi.com/guides/coord-convert-guides-1252)
