地理编码 — API 文档 - 地图帮 GeoAPI 开放平台

接口说明

地址 → 经纬度，支持全国地址解析

输入示例：地址：北京市朝阳区阜通东大街6号；城市：北京

返回示例：返回北京市 · 北京市 · 朝阳区的结构化地址信息，以及坐标 116.480881,39.989410。

请求地址

GEThttps://cloud.dtbgis.com/api/v1/geocode

鉴权方式

在 HTTP Header 中携带你的 API Key：

X-API-Key: 你的API-Key

每个 Key 绑定已购接口与额度，调用成功扣减 1 次；调用失败（参数错误等）不扣额度。未开通该接口返回 403，额度耗尽返回 429。

请求参数

参数	必填	说明	示例 / 默认值
`address`	必填	待解析的地址字符串	`北京市朝阳区阜通东大街6号`
`city`	可选	城市（可提升解析精度）	`北京`

请求示例

curl -H "X-API-Key: 你的API-Key" \
  "https://cloud.dtbgis.com/api/v1/geocode?address=%E5%8C%97%E4%BA%AC%E5%B8%82%E6%9C%9D%E9%98%B3%E5%8C%BA%E9%98%9C%E9%80%9A%E4%B8%9C%E5%A4%A7%E8%A1%976%E5%8F%B7&city=%E5%8C%97%E4%BA%AC"

import requests

resp = requests.get(
    "https://cloud.dtbgis.com/api/v1/geocode?address=%E5%8C%97%E4%BA%AC%E5%B8%82%E6%9C%9D%E9%98%B3%E5%8C%BA%E9%98%9C%E9%80%9A%E4%B8%9C%E5%A4%A7%E8%A1%976%E5%8F%B7&city=%E5%8C%97%E4%BA%AC",
    headers={"X-API-Key": "你的API-Key"},
)
print(resp.status_code, resp.json())

fetch("https://cloud.dtbgis.com/api/v1/geocode?address=%E5%8C%97%E4%BA%AC%E5%B8%82%E6%9C%9D%E9%98%B3%E5%8C%BA%E9%98%9C%E9%80%9A%E4%B8%9C%E5%A4%A7%E8%A1%976%E5%8F%B7&city=%E5%8C%97%E4%BA%AC", {
  headers: { "X-API-Key": "你的API-Key" }
})
  .then(r => r.json())
  .then(console.log);

返回结果说明

所有接口统一返回 JSON 信封结构：

{
  "code": 200,
  "msg": "success",
  "data": { ... },
  "quota_remaining": 9999
}

字段	说明
`code`	业务状态码，`200` 表示成功
`msg`	状态描述，成功为 `success`
`data`	本接口为上游服务代理，`data` 为高德地图 Web 服务的原始响应，字段以官方文档为准
`quota_remaining`	本接口剩余可用调用次数

上游异常时 HTTP 仍为 200，需检查 data.status 判断上游是否成功（此类情况通常由系统自动切换 Key 处理）。

错误码

错误以统一结构返回：{"detail": {"code": 429, "msg": "..."}}

HTTP	含义	常见原因 / 处理
`400`	参数错误	缺少必填参数或格式不合法
`401`	鉴权失败	API Key 缺失、不存在、已停用或已过期
`403`	权限不足	该 Key 未开通此接口，请购买对应额度
`429`	额度耗尽 / 限流	额度用完需续费；或超过速率（60 秒 200 次）
`404`	资源不存在	路径错误，或查询对象无数据
`503`	上游不可用	服务商暂时异常，稍后重试

完整错误码见文档首页 · 错误码总览。