坐标系转换（批量）：一次性转换最多 20 个 GPS 点位
# 坐标系转换（批量）：一次性转换最多 20 个 GPS 点位
> 接口：坐标系转换（apiCode=1252，接入点 1）· 免费 · 返回 JSON · 适用人群：全栈工程师、数据处理者 · 阅读时间：约 6 分钟
## TL;DR
- 接入点 1 的 `location` 参数用 `;` 分隔多个点，**单次请求最多 20 个**坐标。
- 超过 20 个点需「分批循环」，每批 ≤20，再按返回顺序拼回。
- 返回 `resultList` 顺序与输入一一对应，无需额外匹配。
## Why
轨迹、门店、车辆等场景往往是成百上千个点要统一转系。一次只转一个点既慢又费额度。本篇给出「单批 20 点 + 超量自动分批」的生产级写法，让你一次处理任意规模的坐标列表。
## What
前置条件：已跑通单点调用（见[坐标系转换：5 分钟接入](https://www.showapi.com/guides/coord-convert-quickstart-1252)）。
| 项 | 值 |
|----|----|
| 接口地址 | `https://route.showapi.com/1252-1?appKey={your_appKey}` |
| 关键参数 | `from`、`to`、`location`（最多 20 个点，`;` 分隔） |
| 返回 | `resultList[]`，顺序与输入对应 |
## How
**步骤 1：组装单批请求**，20 个点用 `;` 拼接：
```python
import requests
app_key = "YOUR_APPKEY"
points = [(113.194329, 23.234704), (113.20, 23.24), ...] # 最多 20 个/批
def convert_batch(points, frm="WGS84", to="GCJ02"):
location = ";".join(f"{lng},{lat}" for lng, lat in points)
resp = requests.post(
"https://route.showapi.com/1252-1",
params={"appKey": app_key},
data={"from": frm, "to": to, "location": location},
timeout=10,
).json()
body = resp["showapi_res_body"]
if body.get("ret_code") != 0:
raise RuntimeError(body)
return [tuple(it["output"]) for it in body["resultList"]]
```
**步骤 2：超过 20 个点自动分批**（生产级写法，带指数退避重试）：
```python
import time
def convert_all(points, frm="WGS84", to="GCJ02", batch=20):
out = []
for i in range(0, len(points), batch):
chunk = points[i:i + batch]
for attempt in range(3):
try:
out.extend(convert_batch(chunk, frm, to))
break
except Exception as e:
if attempt == 2:
raise
time.sleep(2 ** attempt) # 1s, 2s
return out
```
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.20%2C23.24"
```
Node.js（fetch）：
```javascript
async function convertBatch(points, appKey, frm = "WGS84", to = "GCJ02") {
const location = points.map(([lng, lat]) => `${lng},${lat}`).join(";");
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 10000);
try {
const resp = await fetch(`https://route.showapi.com/1252-1?appKey=${appKey}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ from: frm, to, location }),
signal: controller.signal,
});
const res = (await resp.json()).showapi_res_body;
if (res.ret_code !== 0) throw new Error(JSON.stringify(res));
return res.resultList.map(it => it.output);
} finally { clearTimeout(timer); }
}
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"ret_code": 0,
"resultList": [
{ "input": [113.194329, 23.234704], "output": [113.19971018888167, 23.232115136208677] },
{ "input": [113.20, 23.24], "output": [113.2053, 23.2374] }
]
}
}
```
| 字段 | 说明 |
|------|------|
| `resultList[].output` | 与输入顺序对应的转换后坐标 |
## 进阶 / 边界
- **硬上限 20 个/请求**：超出必须在客户端/服务端分批，接口不接受更多点。
- **顺序一致**：`resultList` 与 `location` 中点的顺序一一对应，可直接按下标拼回原列表。
- 大批量可结合[本地缓存](https://www.showapi.com/guides/coord-convert-cache-1252)与[CSV 实战](https://www.showapi.com/guides/coord-convert-csv-1252)落地。
## FAQ
**Q1：单次最多能转几个点？**
A：接入点 1 单次请求 `location` 最多 20 个坐标点。
**Q2：超过 20 个会怎样？**
A：需自行分批（每批 ≤20）循环调用；接口不会一次接受更多点。
**Q3：返回顺序和输入顺序一致吗？**
A：一致，`resultList` 按下标对应输入，无需再匹配。
**Q4：批量失败如何重试？**
A：建议指数退避（如 1s、2s）最多 2~3 次，避免瞬时抖动放大为整体失败。
**Q5：分批会多消耗免费档位吗？**
A：是的，批次数越多请求越多；重复坐标可先去重或缓存（见成本管控篇）。
## 相关能力 / 下一步阅读
- [坐标系转换：5 分钟接入，从第一条 WGS84→GCJ02 结果开始](https://www.showapi.com/guides/coord-convert-quickstart-1252)
- [Python 实战：把一份 CSV 里的 GPS 经纬度批量转成高德坐标](https://www.showapi.com/guides/coord-convert-csv-1252)
- [免费接口的成本管控：坐标系转换的本地缓存与批量合并策略](https://www.showapi.com/guides/coord-convert-cache-1252)
- **本系列共 12 篇**：查看[坐标系转换指南总目录](https://www.showapi.com/guides/coord-convert-guides-1252)
