经纬度解析 API 接口文档

经纬度解析 API 将坐标转换为可读地址，返回省份、城市、区县、街道与行政区划编码（adcode），适用于门店定位、用户城市识别、配送区域归属和业务地址校验等场景。

快速开始

三步完成首次调用：

注册并登录控制台：https://api-bus.suiyos.com/console/login
创建 API Key：登录后进入「我的 API Key」页，点击「创建 API Key」，复制生成的 sk-gw- 开头密钥（明文仅展示一次，请妥善保存）
首次调用：使用下方域名与密钥发起请求，2 分钟内完成首单调试

调用地址

形态	地址
子域名（推荐）	`https://adcode.gw.api-bus.suiyos.com/{path}`
路径兼容	`https://api-bus.suiyos.com/gateway/adcode/{path}`

两种形态等价，新接入请优先使用子域名形态。

鉴权方式

所有请求必须在请求头中携带 API Key，二选一：

X-API-Key: sk-gw-xxxxxxxxxxxxxxxx
# 或
Authorization: Bearer sk-gw-xxxxxxxxxxxxxxxx

接口：经纬度解析

将经纬度坐标解析为行政区划与详细地址。

请求方式：POST
请求路径：/localGeo/getGeo
Content-Type：application/json

请求参数

参数	类型	必填	说明
`lng`	string	是	经度，如 `116.56183`
`lat`	string	是	纬度，如 `35.320279`

请求示例

curl -X POST 'https://adcode.gw.api-bus.suiyos.com/localGeo/getGeo' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk-gw-xxxxxxxxxxxxxxxx' \
  -d '{"lng":"116.56183","lat":"35.320279"}'

响应示例

{
  "adcode": "370811",
  "city": "济宁市",
  "district": "任城区",
  "formatAddress": "山东省济宁市任城区刘街村",
  "level": "district",
  "province": "山东省",
  "street": "刘街村"
}

响应字段

字段	类型	说明
`adcode`	string	行政区划编码，可用于区域匹配、权限分区与数据统计
`province`	string	省份
`city`	string	城市
`district`	string	区县
`street`	string	街道
`formatAddress`	string	拼接后的完整地址
`level`	string	命中行政层级：`province` / `city` / `district`

错误码

状态码	错误码	含义	处理建议
401	`UNAUTHORIZED`	API Key 缺失、无效或已禁用	检查请求头是否携带有效 `sk-gw-` Key，或在控制台重新创建
403	`SUBSCRIPTION_ACCESS_DENIED`	账号无有效订阅或已被禁用	前往控制台开通/续订服务
404	`NOT_FOUND`	API 不存在或已停用	核对调用地址中的编码是否正确
429	`SUBSCRIPTION_QPS_EXCEEDED`	超过接口每秒调用额度	降低调用频率，或升级订阅提升 QPS
429	`SUBSCRIPTION_DAILY_LIMIT_EXCEEDED`	超过每日调用额度	次日恢复，或升级订阅提升日额度
502	`BAD_GATEWAY`	上游服务不可达	稍后重试，如持续出现请联系客服
504	`GATEWAY_TIMEOUT`	上游响应超时	稍后重试，如持续出现请联系客服

错误响应统一为 JSON 结构：

{ "code": "UNAUTHORIZED", "message": "缺少 API Key，请通过 Authorization: Bearer 或 X-API-Key 提供" }

使用说明

配额：接口按订阅方案计费，包含每秒调用数（QPS）与每日调用数上限，超出返回 429；具体额度请在控制台「订阅」页查看
调用日志：控制台「调用日志」页可查看每次调用的路径、状态码、耗时与错误信息，便于排查线上问题
API Key 管理：可在控制台对 Key 进行禁用/删除；密钥明文仅在创建时展示一次，平台不保存明文，丢失需重建
上传规范：请勿将 API Key 写入公开仓库、前端页面或分享给他人；如疑似泄露，请立即在控制台禁用并重建

常见问题

经纬度转行政区和经纬度转 adcode 有什么区别？

经纬度转行政区关注坐标所在的省市区名称；经纬度转 adcode 会进一步返回行政区划编码，便于系统做区域匹配、权限分区和数据统计。本接口一次请求同时返回两者。

坐标返回空或层级不准确怎么办？

请确认经纬度格式（小数形式，如 116.56183），并检查坐标是否在中国大陆范围内；边界或偏远区域可能命中到上一级行政区（level 字段会标明实际命中层级）。