地理编码

接口说明

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

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

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

请求地址

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

鉴权方式

在 HTTP Header 中携带你的 API Key：

X-API-Key: 你的API-Key

每个 API Key 绑定已购接口与流量豆，调用成功扣减对应流量豆；调用失败（参数错误等）不扣流量豆。未开通该接口返回 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` 字段说明」
`quota_remaining`	本次调用后剩余可用流量豆数量

本接口 data 为高德原始 JSON 透传，坐标系 GCJ-02。如需与厂商解耦、字段稳定的统一格式，请使用「地理编码 v2」（/api/v2/geocode）。

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "status": "1",
    "info": "OK",
    "infocode": "10000",
    "count": "1",
    "geocodes": [
      {
        "formatted_address": "北京市朝阳区阜通东大街6号",
        "country": "中国",
        "province": "北京市",
        "citycode": "010",
        "city": "北京市",
        "district": "朝阳区",
        "adcode": "110105",
        "street": "阜通东大街",
        "number": "6号",
        "location": "116.480881,39.989410",
        "level": "门牌号"
      }
    ]
  },
  "quota_remaining": 9999
}

`data` 字段说明

字段	类型	说明	示例
`status`	string	上游状态码，"1" 表示成功	`1`
`info`	string	上游状态说明	`OK`
`infocode`	string	上游状态码明细	`10000`
`count`	string	结果条数	`1`
`geocodes`	array	地理编码结果列表	—
`formatted_address`	string	结构化地址全称	`北京市朝阳区阜通东大街6号`
`country`	string	国家	`中国`
`province`	string	省 / 直辖市	`北京市`
`citycode`	string	城市电话区号	`010`
`city`	string	城市名称	`北京市`
`district`	string	区 / 县	`朝阳区`
`adcode`	string	行政区划编码	`110105`
`street`	string	街道名	`阜通东大街`
`number`	string	门牌号	`6号`
`location`	string	经纬度，格式 lng,lat（GCJ-02）	`116.480881,39.989410`
`level`	string	匹配级别：省 / 市 / 区县 / 道路 / 门牌号等	`门牌号`

错误码

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

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

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