🗺️ 地址转经纬度 API v1 · 文档
✅ 接口信息
🔑 鉴权 Token
当前 token（测试用，生产部署请改环境变量）：
geocode-demo-token-2026
修改方式：export GEOCODE_API_TOKEN=<32位随机串> 后重启服务。
📤 请求参数
| 字段 | 必填 | 位置 | 说明 |
|---|
address | ✅ | query / body | 要查询的中文地址，越精确越好 |
city | - | query / body | 城市名（如"漳州市"），辅助去歧义，不传则用 IP 定位兜底 |
token | ✅ | query / body / Header | 访问凭证，三种传法任选其一 |
📥 返回字段（精简版）
| 字段 | 类型 | 说明 |
|---|
code | int | 0 = 成功；其他 = 错误码 |
success | bool | 是否成功 |
message | string | 成功时 OK，失败时错误描述 |
data.latitude | number | 纬度 |
data.longitude | number | 经度 |
data.coord | string | 格式化坐标：lat, lng |
data.formatted_address | string | 腾讯标准化后的完整地址 |
data.title | string | POI 标题（如"招商海翼文璟苑-7栋"） |
data.province | string | 省/直辖市 |
data.city | string | 城市 |
data.district | string | 区/县 |
data.warnings | string[] | 警告（楼栋号不匹配 / 腾讯偏差大时会提示，调用方可以弹窗提醒） |
🧪 调用示例
1) cURL · GET
curl -G 'http://localhost:8000/api/v1/geocode' \
--data-urlencode 'address=漳州市龙海区海澄镇文璟苑7-702' \
--data-urlencode 'city=漳州市' \
--data-urlencode 'token=geocode-demo-token-2026'
2) cURL · POST JSON
curl -X POST 'http://localhost:8000/api/v1/geocode' \
-H 'Content-Type: application/json' \
-d '{
"address": "漳州市龙海区石码镇领秀锦江8栋2单元2508",
"city": "漳州市",
"token": "geocode-demo-token-2026"
}'
3) Python 调用
import requests, urllib.parse
url = 'http://localhost:8000/api/v1/geocode'
params = {
'address': '北京市朝阳区望京SOHO',
'token': 'geocode-demo-token-2026'
}
r = requests.get(url, params=params, timeout=20)
j = r.json()
if j['success']:
d = j['data']
print(d['formatted_address'])
print('纬度:', d['latitude'], '经度:', d['longitude'])
4) Header Authorization（推荐放 token 在这里，URL 不泄露）
curl -G 'http://localhost:8000/api/v1/geocode' \
-H 'Authorization: Bearer geocode-demo-token-2026' \
--data-urlencode 'address=洪达建材'
❌ 错误码
| code | HTTP | 说明 |
|---|
| 0 | 200 | 查询成功 |
| 400 | 400 | 缺少必填参数 address |
| 401 | 401 | 缺少 token |
| 403 | 403 | token 错误 |
| 422 | 422 | 不支持的地址类型（非中文） |
| 502 | 502 | 腾讯地理编码服务异常 |