坐标系转换接口说明：WGS84 / GCJ02 / BD09 互转、参数与调用示例

1 技术简介

本接口提供坐标系经纬度转换与地理编码 / 逆地理编码两类能力，服务于地图、导航、定位、LBS 等场景中的坐标系统一与地址结构化。

• 坐标系互转：支持 WGS84（GPS 原始坐标）、GCJ02（国测局加密坐标，国内主流地图采用）、BD09（百度坐标系）三者之间的相互换算；
• 经纬度 → 地址（逆地理编码）：输入坐标与坐标系类型，返回省 / 市 / 区 / 街道 / 门牌 / 商圈等结构化地址；
• 地址 → 经纬度（地理编码）：输入地址文本，返回 GCJ02 坐标与置信度。

适用于需要在多套地图坐标系之间做坐标对齐、对 GPS 轨迹做地址解析、或把文本地址转成可定位坐标的工程场景。

2 能力概览

3 适用场景

• 多源轨迹归一：GPS 设备（WGS84）采集的轨迹需与国内地图（GCJ02）或百度地图（BD09）叠加展示时，先做坐标系换算再渲染；
• 地址解析：物流、O2O、外卖等场景将经纬度转成省市区 / 街道门牌，用于区域划分与展示；
• 文本定位：把用户输入或历史数据里的文本地址转成坐标，写入地理数据库；
• 地图开发：小程序 / App / Web 地图在切换底图（高德 / 百度 / 自研）时统一坐标基准。

4 接入流程

1. 开通服务，获取 appcode（调用凭证）；
2. 明确业务要用的坐标系类型（from 参数取值见 §5 参数表）；
3. 按下方参数表与示例发起 GET 请求，Authorization 头携带 APPCODE <appcode>；
4. 解析 JSON 返回，按 ret_code 判定成功 / 失败，再做坐标使用；
5. 异常时按 §8 错误码排查表定位。

![接入流程示意图](https://res-showapi.oss-cn-hangzhou.aliyuncs.com/1day-delete/coordinat_convert_01.png)

5 调用示例与返回结构

本服务提供两个接口，均使用 appcode 鉴权：

调用地址与鉴权信息以控制台开通页为准；本文示例统一用占位符 <调用地址> 与 YOUR_APPCODE。

5.1 经纬度转地址（/location_address）

请求参数（Query）

from 取值对照

返回字段

addressComponent 内字段：country（国家）、province（省）、city（城市）、district（区县）、town（乡镇，需设 extensions_town=true 才返回）、street（街道）、street_number（门牌号）、adcode（行政区划代码）、direction（与当前坐标点的方向）、distance（与当前坐标点距离，有门牌号时返回）、country_code / country_code_iso / country_code_iso2（国家编码及英文缩写）、city_level（城市所在级别，主要对国外地址有参考意义）。

返回示例（成功）

{
   
  "showapi_res_error": "",
  "showapi_fee_num": 0,
  "showapi_res_code": 0,
  "showapi_res_id": "63d9d6e50de376870ecd5dd8",
  "showapi_res_body": {
   
    "ret_code": 0,
    "location": {
    "lng": 116.32298703399, "lat": 39.983424051248 },
    "formatted_address": "北京市海淀区中关村大街",
    "addressComponent": {
   
      "country": "中国",
      "province": "北京市",
      "city": "北京市",
      "district": "海淀区",
      "adcode": "110108",
      "street": "中关村"
    },
    "business": "人民大学,中关村,苏州街"
  }
}

5.2 地址转经纬度（/address_location）

请求参数（Query）

返回字段

返回示例（成功）

{
   
  "showapi_res_error": "",
  "showapi_fee_num": 1,
  "showapi_res_code": 0,
  "showapi_res_id": "620b52030de37618171c3260",
  "showapi_res_body": {
   
    "ret_code": 0,
    "location": {
    "lng": 116.327252, "lat": 39.999652 },
    "precise": 1,
    "confidence": 0.9,
    "level": "POI"
  }
}

5.3 多语言调用示例

以下示例中 调用地址 与 YOUR_APPCODE 为占位符，替换为控制台实际值后即可运行。

Python

import requests

url = "<调用地址>/location_address"
headers = {
   "Authorization": "APPCODE YOUR_APPCODE"}
params = {
   "lng": "116.32298703399", "lat": "39.983424051248", "from": "5"}
resp = requests.get(url, headers=headers, params=params, timeout=5)
print(resp.status_code, resp.text)

Java（HttpClient）

// 使用 JDK 内置 HttpClient，无需额外依赖
// 调用地址与 appcode 替换为控制台实际值
Map<String, String> q = new LinkedHashMap<>();
q.put("lng", "116.32298703399");
q.put("lat", "39.983424051248");
q.put("from", "5");
String host = "<调用地址>"; // 控制台开通后获取的完整调用地址
String path = "/location_address";
var sb = q.entrySet().stream()
    .map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8)
        + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
    .collect(Collectors.joining("&"));
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(host + path + "?" + sb))
    .header("Authorization", "APPCODE YOUR_APPCODE")
    .GET().timeout(Duration.ofSeconds(5)).build();
HttpResponse<String> resp =
    HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.statusCode() + " " + resp.body());

curl

curl -G "<调用地址>/location_address" \
  -H "Authorization: APPCODE YOUR_APPCODE" \
  --data-urlencode "lng=116.32298703399" \
  --data-urlencode "lat=39.983424051248" \
  --data-urlencode "from=5"

![返回字段结构](https://res-showapi.oss-cn-hangzhou.aliyuncs.com/1day-delete/coordinat_convert_02.png)

6 在线调试实录

用例 1：百度坐标反查地址

在控制台调试面板切到"经纬度转地址"，Query 填 lng=116.32298703399、lat=39.983424051248、from=5（百度坐标系），发起请求。返回 showapi_res_code=0，showapi_res_body.ret_code=0，addressComponent 逐层给出国家 / 省 / 市 / 区县，business 给出最多 3 个商圈名。

用例 2：坐标系选错的排查

同一组 WGS84 坐标若误按 from=5 提交，得到的地址偏移可达数百米——因为 GCJ02 / BD09 相对 WGS84 存在非线性偏移。排查方法：先确认坐标来源（GPS 芯片输出为 WGS84），再按来源选 from，最后用已知地标的坐标做对照验证。

用例 3：地址文本转坐标

切到"地址转经纬度"，address=清华大学，返回 location（GCJ02 坐标）与 confidence。若 precise=0，说明命中的是区县级而非 POI 级，地址粒度需要细化。

![在线调试示意](https://res-showapi.oss-cn-hangzhou.aliyuncs.com/1day-delete/coordinat_convert_06.png)

7 调用限制与规范

8 能力边界与免责

支持

• WGS84 / GCJ02 / BD09 主流坐标系之间的换算；
• 中国大陆地址的逆 / 正地理编码；国外地址按 city_level 说明参考使用。

不支持 / 边界

• 不返回测绘级精度的坐标（定位用途以地图服务为准）；
• town 字段需显式设置 extensions_town=true 才返回；
• 地址文本过于模糊（如只有"某市"）时置信度低，建议补充区 / 街道。

免责

返回数据仅供业务参考，涉及导航、测绘、法律地址认定等用途，请以权威测绘成果为准。

9 错误码排查

网关层（showapi_res_code ≠ 0 的常见取值）

业务层（showapi_res_code=0 时看 showapi_res_body）

![坐标体系对照](https://res-showapi.oss-cn-hangzhou.aliyuncs.com/1day-delete/coordinat_convert_03.png)

10 技术 FAQ

Q1：from 该传几？按什么原则选？
按坐标来源选：GPS 原始 → 1；高德 / 国内地图 → 3；百度地图 → 5。拿不准时用已知地标坐标对照验证。

Q2：返回的坐标是 WGS84 还是 GCJ02？
地址转经纬度返回的是 GCJ02 坐标；坐标系换算结果取决于输入与目标体系，使用前标注好坐标基准。

Q3：business 为什么只有 0~3 个值？
商圈信息最多返回 3 个，属正常设计；需要更多 POI 时建议叠加 POI 检索。

Q4：计次规则？
HTTP 200 才计次，非 200（含网关错误）不计次。

Q5：能否批量调用？
接口为单次查询；批量场景在业务层做并发 + 缓存，结果按坐标 key 去重。

Q6：国外地址支持吗？
字段层面有 country / country_code 支持，城市层级参考意义有限（city_level 说明），国内地址为主要使用范围。

11 内容小结

工程落地时，建议把「坐标来源判定 → from 选择 → 调用 → 结果缓存」封装成统一服务，上层业务只关心"地址"与"坐标"两种实体。