地址 POI 精确定位（模糊地址 → C1–C5 决策）

接口说明

模糊/脏地址落到可解释 POI：C1–C5 分类码 + 选用 POI + 坐标 + 判定理由；宁可诚实拒落不静默错点

输入示例：地址：广东省广州市黄埔区广本（可附校正地址、限定城市）

返回示例：返回 C1–C5 采纳决策：如 C1 精确匹配「广汽本田汽车有限公司」+ 坐标 + 可读判定理由；无法可靠定位时诚实返回 C4/C5，不静默给错点。

请求地址

POSThttps://cloud.dtbgis.com/api/v1/address/poi-resolve

鉴权方式

在 HTTP Header 中携带你的 API Key：

X-API-Key: 你的API-Key

每个 API Key 绑定已购接口与流量豆，调用成功扣减对应流量豆；调用失败（参数错误等）不扣流量豆。未开通该接口返回 403，流量豆不足返回 429。

请求参数

本接口为 POST 请求：以下参数以 JSON 对象放在请求体中提交（Content-Type: application/json），不拼接在 URL 上。

参数	必填	说明	示例 / 默认值
`address`	必填	待定位地址文本（可为脏地址/口语别名，≤512 字符）	`广东省广州市黄埔区广本`
`corrected_address`	可选	可选校正地址（B 检索源，≤512 字符）	—
`city_hint`	可选	限定城市（市名或 adcode），提供时检索启用 citylimit	—

请求示例

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 你的API-Key" \
  -d '{"address": "广东省广州市黄埔区广本"}' \
  "https://cloud.dtbgis.com/api/v1/address/poi-resolve"

import requests

resp = requests.post(
    "https://cloud.dtbgis.com/api/v1/address/poi-resolve",
    json={"address": "广东省广州市黄埔区广本"},
    headers={"X-API-Key": "你的API-Key"},
)
print(resp.status_code, resp.json())

fetch("https://cloud.dtbgis.com/api/v1/address/poi-resolve", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "你的API-Key",
  },
  body: JSON.stringify({"address": "广东省广州市黄埔区广本"}),
})
  .then(r => r.json())
  .then(console.log);

返回结果说明

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

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

字段	说明
`code`	业务状态码，`200` 表示成功
`msg`	状态描述，成功为 `success`
`data`	查询结果对象，字段见下方「`data` 字段说明」
`quota_remaining`	本次调用后剩余可用流量豆数量

顶层信封另含 attribution（数据来源声明）。坐标为 GCJ-02（location 为 lng,lat 文本，lng / lat 为拆好的数值）。status=upstream_error 时不计费、retryable=true，可安全重试。

响应示例

{
  "code": 200,
  "msg": "success",
  "quota_remaining": 98765,
  "attribution": "POI 候选来自高德开放平台关键词检索；分类判定为地图帮规则引擎结果，C2/C3 为代理/上卷点，落库前请按业务口径抽检",
  "data": {
    "class_code": "C1",
    "class_name": "精确匹配",
    "decision": "采纳",
    "poi": {
      "id": "B00FWZ0EXH",
      "name": "广汽本田汽车有限公司",
      "address": "广本路1号",
      "location": "113.448792,23.121623",
      "lng": 113.448792,
      "lat": 23.121623,
      "type": "公司企业;公司;公司",
      "adname": "黄埔区",
      "cityname": "广州市"
    },
    "score": 110.0,
    "why": "exact_c;alias~q",
    "reason": "候选「广汽本田汽车有限公司」与查询地址强一致",
    "status": "resolved",
    "retryable": false,
    "trace_id": "9f2c1a7b3e5d4a08",
    "candidates": null
  }
}

`data` 字段说明

字段	类型	说明	示例
`class_code`	string	C1 精确 / C2 近似 / C3 取上一级 / C4 模糊无法找到 / C5 无法找到；upstream_error 时为 null	`C1`
`class_name`	string	分类中文名	`精确匹配`
`decision`	string	采纳 / 未找到 / 不采纳	`采纳`
`poi`	object	选用 POI；C4 / C5 为 null	—
`id`	string	POI 唯一 ID	`B00FWZ0EXH`
`name`	string	POI 名称	`广汽本田汽车有限公司`
`address`	string	POI 地址	`广本路1号`
`location`	string	经纬度 lng,lat（GCJ-02）	`113.448792,23.121623`
`lng`	float	经度（数值）	`113.448792`
`lat`	float	纬度（数值）	`23.121623`
`type`	string	POI 分类（大类;中类;小类）	`公司企业;公司;公司`
`adname`	string	区县名称	`黄埔区`
`cityname`	string	城市名称	`广州市`
`score`	number	规则引擎打分（可解释审计用）	`110.0`
`why`	string	打分特征标签（exact_c;alias~q 等）	`exact_c;alias~q`
`reason`	string	人可读判定理由（质检/客服友好）	`候选「广汽本田汽车有限公司」与查询地址强一致`
`status`	string	resolved / upstream_error（不计费可重试）	`resolved`
`retryable`	bool	仅 upstream_error 为 true	`false`
`trace_id`	string	审计追踪 ID，客诉排查时请一并提供	`9f2c1a7b3e5d4a08`
`candidates`	array	options.return_candidates=true 时返回打分候选摘要（≤5，各含 name/source/score/why）；默认 null	`[{name, source, score, why}]`

错误码

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

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

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