适用场景与技术痛点
在日常业务系统中，地址信息常以自由文本形式出现：电商订单收货地址、快递面单、CRM客户资料、办公场所登记等场景下，用户可能输入“张三 13812345678 上海市浦东新区张江镇科苑路88号 201203”这样的混合字符串。如果靠正则或硬编码逐项提取，不仅开发维护复杂度高，而且容易遗漏或误判（例如“上海市”和“上海”的简称处理、姓名与地址的边界识别、手机号格式校验等）。
中文地址解析API提供了一站式解决方案：只需传入原始字符串，即可返回结构化字段——省、市、区县、街道、详细地址、姓名、手机号和邮编。该API纯本地正则算法，无上游依赖，响应时间通常在毫秒级，适合高并发场景。
接口能力边界
- 支持范围：中国34个省级行政区（含港澳台）及其简称（如“北京”→“北京市”，“新疆”→“新疆维吾尔自治区”）。
- 输入限制：单次请求
address字段长度 ≤ 500 字符，支持姓名、手机号、邮编与地址混合输入。 - 输出字段：
province,city,district,street,detail,name,phone,zipcode，以及原始字符串original（手机号中间四位会被脱敏显示为****）。 - QPS限制：接口默认QPS为20/s（匿名调用可能更严格，建议使用API Key鉴权以提升配额）。
- 适用场景：电商收货地址自动拆分、快递下单智能填充、客户资料清洗、办公地址结构化入库。
请求参数与鉴权
请求方式
POST https://v1.apizero.cn/api/address-parse
Header参数
| 参数名 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
Authorization | 否 | string | 格式Bearer sk_live_xxx（未登录匿名调用受更严格限流） |
Content-Type | 是 | string | application/json |
注意：虽然没有强制要求Authorization，但在生产环境中强烈建议使用API Key，以保证更高的QPS配额和稳定性。获取API Key的方式请参考官方文档。
请求体
请求体是一个JSON对象，必须包含address字段：
{ "address": "张三 13812345678 上海市浦东新区张江镇科苑路88号 201203" }| 字段名 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
address | 是 | string | 中文地址字符串，支持姓名/手机/邮编混合输入，长度 ≤ 500 |
curl示例：快速验证接口
以下curl命令可直接在终端运行，替换$APIZERO_API_KEY为你自己的API Key：
curl -sS \ -X POST \ -H "Authorization: Bearer $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"address": "李四 13987654321 广东省广州市天河区体育西路100号 510620"}' \ "https://v1.apizero.cn/api/address-parse"返回示例：
{ "code": 0, "data": { "city": "广州市", "detail": "体育西路100号", "district": "天河区", "name": "李四", "original": "李四 139****4321 广东省广州市天河区体育西路100号 510620", "phone": "139****4321", "province": "广东省", "street": "", "zipcode": "510620" }, "msg": "成功", "request_id": "abc123def456" }Python代码接入
使用requests库可以方便地集成到后端项目中：
import requests import json API_URL = "https://v1.apizero.cn/api/address-parse" API_KEY = "sk_live_xxx" # 替换为真实Key def parse_address(address_str): headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } payload = {"address": address_str} resp = requests.post(API_URL, headers=headers, json=payload) if resp.status_code != 200: print(f"HTTP error: {resp.status_code}") return None result = resp.json() if result.get("code") != 0: print(f"API error: {result.get('msg')}") return None return result["data"] # 测试 addr = "王五 15012345678 北京市海淀区中关村大街1号 100080" data = parse_address(addr) if data: print(json.dumps(data, ensure_ascii=False, indent=2))输出：
{ "city": "北京市", "detail": "中关村大街1号", "district": "海淀区", "name": "王五", "original": "王五 150****5678 北京市海淀区中关村大街1号 100080", "phone": "150****5678", "province": "北京市", "street": "", "zipcode": "100080" }返回值字段解读
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 状态码（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 | 手机号（脱敏，中间四位为****） |
data.zipcode | string | 邮编（若输入中包含） |
data.original | string | 原始输入字符串（脱敏后） |
注意事项：
street可能为空字符串，表示未能提取到街道/镇信息；但detail中通常包含了完整地址。- 姓名和手机号并非必填字段，若输入中没有，返回中对应字段为空字符串。
- 邮编若输入中没有，
zipcode为空字符串。
常见错误与排查
| 错误现象 | 可能原因 | 解决方式 |
|---|---|---|
返回code: 400 | 请求体格式错误，或address字段缺失 | 检查JSON格式，确保address为字符串且非空 |
返回code: 401 | API Key无效或未传 | 检查Header中Authorization值是否正确 |
返回code: 429 | 请求超限 | 降低请求频率，或使用API Key提升配额 |
返回数据中phone为空 | 输入中无手机号，或手机号格式与常见正则不匹配（如带“+86”前缀） | 确认输入是否包含11位数字；若有前缀，建议先预处理 |
返回数据中province、city等不完整 | 输入地址太短或不规范（如只写了“上海”无街道） | 尽量提供完整地址；算法依赖省市区级联规则 |
工程化注意事项
批量处理：如果需要对大量地址进行解析（如数据清洗），建议在协程或异步框架下并发调用，但注意总QPS不超过20/s。若使用API Key，可在官方文档中查看具体QPS说明。
数据脱敏处理：接口返回的
phone已脱敏，但原始请求中的手机号会以明文传输。生产环境中建议在客户端或代理层对原始输入进行脱敏后再传输（例如记录日志时脱敏）。异常重试：网络抖动可能导致请求失败，建议实现指数退避重试（如第一次等待1s，第二次2s，第三次4s），最大重试3次。
缓存策略：对于重复出现的地址（如固定仓库地址），可在业务侧缓存解析结果，减少不必要的API调用。
输入长度校验：
address字段限制500字符，超出部分会被截断或导致400错误，建议前端做长度校验。多语言兼容：当前接口仅支持中文地址，若遇到中英混写或繁体字，结果可能不准确。建议在调用前先进行简繁转换。
参考文档
- 接口文档：https://apizero.cn/aidocs/address-parse
- 原始Markdown文档：https://apizero.cn/aidocs/address-parse/raw.md
本文所有示例均基于上述文档中的真实参数编写，请以官方最新文档为准。
