地址清洗（离线省市区识别与补全）

接口说明

残缺地址离线补全省市区（不返回经纬度、不调用在线地理编码）

输入示例：address：深圳市南山区科技园；strict：false

返回示例：返回“地址清洗（离线省市区识别与补全）”的查询结果，包含状态、数据内容和本次调用后的剩余流量豆。

请求地址

POSThttps://cloud.dtbgis.com/api/v1/address/clean

鉴权方式

在 HTTP Header 中携带你的 API Key：

X-API-Key: 你的API-Key

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

请求参数

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

参数	必填	说明	示例 / 默认值
`address`	可选	单条地址文本（与 addresses 互斥，≤512 字符）	`深圳市南山区科技园`
`addresses`	可选	批量地址数组（≤1000 条）	—
`strict`	可选	严格模式：拒绝前缀猜测级命中	`false`

请求示例

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 你的API-Key" \
  -d '{"address": "深圳市南山区科技园", "strict": "false"}' \
  "https://cloud.dtbgis.com/api/v1/address/clean"

import requests

resp = requests.post(
    "https://cloud.dtbgis.com/api/v1/address/clean",
    json={"address": "深圳市南山区科技园", "strict": "false"},
    headers={"X-API-Key": "你的API-Key"},
)
print(resp.status_code, resp.json())

fetch("https://cloud.dtbgis.com/api/v1/address/clean", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "你的API-Key",
  },
  body: JSON.stringify({"address": "深圳市南山区科技园", "strict": "false"}),
})
  .then(r => r.json())
  .then(console.log);

返回结果说明

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

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

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

顶层信封另含 dict_version（离线区划字典版本，如 desktop2021p-20260726）。单条与批量共用同一返回结构：results 数组按输入顺序对应。

响应示例

{
  "code": 200,
  "msg": "success",
  "dict_version": "desktop2021p-20260726",
  "quota_remaining": 9999,
  "data": {
    "total": 1,
    "results": [
      {
        "input": "深圳市南山区科技园",
        "province": "广东省",
        "city": "深圳市",
        "district": "南山区",
        "detail": "科技园",
        "status": "completed_by_dict",
        "province_adcode": "440000",
        "city_adcode": "440300",
        "district_adcode": "440305",
        "no_district_level": false,
        "ambiguous": false,
        "candidates": null,
        "matched_by": { "province": "dict", "city": "exact", "district": "exact" }
      }
    ]
  }
}

`data` 字段说明

字段	类型	说明	示例
`total`	int	结果行数（与输入行数一致）	`1`
`results`	array	清洗结果列表，顺序与输入一致	—
`input`	string	原始输入地址（回显）	`深圳市南山区科技园`
`province`	string	省级全称	`广东省`
`city`	string	市级全称	`深圳市`
`district`	string	区县全称	`南山区`
`detail`	string	剩余详址文本（原样）	`科技园`
`status`	string	complete / completed_by_dict / partial / unrecognized / empty	`completed_by_dict`
`province_adcode`	string	省级 6 位国标 adcode	`440000`
`city_adcode`	string	市级 adcode	`440300`
`district_adcode`	string	区县 adcode	`440305`
`no_district_level`	bool	该市无区县层级（东莞/中山/仙桃等），到市级即完整	`false`
`ambiguous`	bool	区县重名且无上级约束时为 true	`false`
`candidates`	array	歧义候选（≤8，各含省市区名称与 adcode）；无歧义为 null	`[{province, city, district, ...}]`
`matched_by`	object	各级匹配证据：exact / alias / prefix_guess / dict，未命中为 null	`{province: dict, city: exact, district: exact}`

错误码

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

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

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