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

接口说明

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

请求地址

鉴权方式

在 HTTP Header 中携带你的 API Key：

X-API-Key: 你的API-Key

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

请求参数

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

请求示例

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 你的API-Key" \
  -d '{"address": "广东省广州市黄埔区广本", "match_mode": "exact"}' \
  "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": "广东省广州市黄埔区广本", "match_mode": "exact"},
    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": "广东省广州市黄埔区广本", "match_mode": "exact"}),
})
  .then(r => r.json())
  .then(console.log);

返回结果说明

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

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

顶层信封另含 attribution（数据来源声明）。坐标为 GCJ-02（location 为 lng,lat 文本，lng / lat 为拆好的数值）。status=upstream_error 时不计费、retryable=true，可安全重试。match_mode=fuzzy（模糊匹配）时 C4/C5 若有召回则采用地图检索首位回填 poi（class_code 保持 C4/C5，decision=采用检索结果），计费口径与 exact 相同。

响应示例

{
  "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,
    "source_pois": [
      {
        "name": "广汽本田汽车有限公司",
        "address": "广本路1号",
        "location": "113.448792,23.121623",
        "type": "公司企业;公司;公司",
        "adname": "黄埔区",
        "cityname": "广州市"
      }
    ]
  }
}

data 字段说明

class_code 判定原理

分类码是决策层结论（检索 → 打分 → 分类判定），不是又一次地理编码； status=upstream_error 时为 null（不计费可重试）。判定顺序：先在全部候选 （address 第一路 + 校正地址第二路）中取最高分者（同分时行政锚点类型优先， 再取距离更近者），再按下表原理归类。

公交站/地铁站默认不作为采纳落点（options.reject_transit_stops 可关闭）； options.rollup_enabled 默认 true，仅 C5 会尝试上一级行政锚点上卷。

match_mode=fuzzy（模糊匹配）下 C1–C3 与 exact 完全一致；仅最终仍为 C4/C5 且 source_pois 非空时用检索第一条回填 poi，class_code 保持 C4/C5 不升级，decision=采用检索结果。

落库建议：C1 可直接落库；C2/C3 为近似/上卷点，建议按业务口径抽检； C4/C5 在 exact（精确匹配）下明确拒落——「这个地址不能可靠落点」 本身就是有价值的结论，可转人工复核或改用 fuzzy 兜底。

错误码

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

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