适用场景
电商收货地址自动拆分、快递下单页智能填充、CRM客户资料清洗、办公地址结构化入库，这些场景都面临一个共同痛点：用户输入的地址往往是混合字符串，如"张三 13812345678 上海市浦东新区张江镇科苑路88号 201203"。人工拆分效率低且容易出错，而调用中文地址解析API只需一次请求，就能得到省/市/区/街道/详细地址/姓名/手机号/邮编等结构化字段。
接口能力边界
- 纯本地正则算法，无上游依赖，单次请求毫秒级响应。
- 支持34个省级行政区及其简称识别（如「北京」→「北京市」、「新疆」→「新疆维吾尔自治区」）。
- 支持混合输入拆分：姓名、手机号、邮编可出现在地址前后任意位置。
- 请求地址长度限制：≤500字符。
- QPS：20/s（未登录匿名调用有更严格限流，建议携带API Key）。
请求参数与鉴权
鉴权方式
接口支持Bearer Token鉴权（可选）：在请求头中添加Authorization: Bearer sk_live_xxx。推荐生产环境携带Token以获得稳定的限流配额。匿名调用也可使用，但QPS可能较低。
请求体字段
| 字段名 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| address | string | 是 | 中文地址字符串（≤500字符），支持姓名/手机/邮编混合 | "张三 13812345678 上海市浦东新区张江镇科苑路88号 201203" |
请求体必须为JSON对象，Content-Type设置为application/json。
curl 最小可运行示例
以下是一个完整的POST请求，可以直接复制到终端执行（替换$APIZERO_API_KEY为你的真实Key，或不加 -H 行以匿名方式调用）：
curl -sS \ -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{"address": "李四 15987654321 广东省深圳市南山区科技园南区R2-B栋 518057"}' \ "https://v1.apizero.cn/api/address-parse"注意：示例中的
YOUR_API_KEY需要替换成你自己的Key。如果匿名调用，删除-H "Authorization: ..."行即可。
成功响应示例（JSON，已格式化）：
{ "code": 0, "data": { "city": "深圳市", "detail": "科技园南区R2-B栋", "district": "南山区", "name": "李四", "original": "李四 159****1234 广东省深圳市南山区科技园南区R2-B栋 518057", "phone": "159****1234", "province": "广东省", "street": "", "zipcode": "518057" }, "msg": "成功", "request_id": "a1b2c3d4e5f6g7h8i9j0" }Python 代码接入示例
使用Python的requests库即可完成调用。以下是一个最小可运行脚本，包含异常处理和字段打印：
import requests import json # API地址（请替换成真实Key或删除headers行进行匿名调用） url = "https://v1.apizero.cn/api/address-parse" headers = { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY" # 可选，不留则匿名 } payload = { "address": "王五 13600000000 北京市朝阳区望京soho T1-15层 100102" } try: resp = requests.post(url, json=payload, headers=headers, timeout=5) resp.raise_for_status() data = resp.json() if data.get("code") == 0: result = data["data"] print("解析结果：") print(f"省份：{result.get('province')}") print(f"城市：{result.get('city')}") print(f"区县：{result.get('district')}") print(f"街道：{result.get('street')}") print(f"详细地址：{result.get('detail')}") print(f"姓名：{result.get('name')}") print(f"手机号：{result.get('phone')}") print(f"邮编：{result.get('zipcode')}") else: print(f"请求失败，code={data.get('code')}, msg={data.get('msg')}") except requests.exceptions.RequestException as e: print(f"网络异常：{e}") except json.JSONDecodeError: print("响应非JSON格式")运行输出：
解析结果： 省份：北京市 城市：北京市 区县：朝阳区 街道：望京soho T1-15层 详细地址：望京soho T1-15层 姓名：王五 手机号：136****0000 邮编：100102返回值详细解读
成功HTTP状态码为200，响应体JSON结构固定：
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 状态码，0表示成功，非0表示错误 |
| msg | string | 描述信息 |
| request_id | string | 请求唯一标识，可用于排查问题 |
| data | object | 解析结果对象，包含以下字段 |
| data.province | string | 省份名称（带“省”字，直辖市为“北京市”等） |
| data.city | string | 城市名称（直辖市与省同） |
| data.district | string | 区/县级名称 |
| data.street | string | 街道/镇名称（如果存在） |
| data.detail | string | 详细地址（门牌号、楼栋等） |
| data.name | string | 提取的姓名（如无则为空） |
| data.phone | string | 手机号（中间四位掩码，如136****0000） |
| data.zipcode | string | 邮政编码（如无则为空） |
| data.original | string | 原始地址字符串（手机号被掩码处理） |
注意事项：
- 手机号部分返回掩码格式，数据库存储时需注意。
- 如果地址中未包含姓名或邮编，对应字段为空字符串。
street字段可能为空，当地址未明确街道时（如直接写“上海市浦东新区科苑路88号”）。
常见错误与处理
| HTTP状态码 | code | msg | 解决建议 |
|---|---|---|---|
| 400 | 1001 | 参数错误 | 检查address字段是否存在且为字符串 |
| 401 | 1002 | 鉴权失败（仅在使用Token时） | 确认Authorization头格式正确，Key有效 |
| 429 | 1003 | 请求超限 | 降低请求频率或携带API Key提升配额 |
| 500 | 2001 | 服务内部错误 | 重试或查看request_id联系技术支持 |
建议在代码中统一捕获HTTPError并解析响应体中的code与msg。
工程化注意事项
- 请求重试策略：对于429/500错误，采用指数退避重试（如最多3次，间隔1s、2s、4s）。
- 批量处理：如果一次性需要处理大量地址（如CSV导入），建议控制并发数不超过QPS限流（20/s），并携带Token。
- 数据脱敏：返回的
original字段中的手机号已被掩码处理，但若仍需原始手机号，可在请求前自行备份。 - 地址格式预检：建议在调用前做前端校验，如去除多余空格、统一全半角等，可以提高解析准确率。
- Test环境：可在代码中切换请求的url为测试环境（若有），或使用匿名调用进行功能验证。
参考文档
- 中文地址解析API文档
- 原始文档（Markdown）