背景与适用场景

日常开发中，中文地址数据往往以松散格式出现——用户在下单时可能输入“张三 13812345678 上海市浦东新区张江镇科苑路88号 201203”，或快递面单上“北京市海淀区中关村大街1号 李四 13987654321”等混合字符串。这类数据如果靠人工拆分，效率低且易出错。在以下场景中，自动化的地址解析能力尤为重要：

• 电商订单系统：接收用户填写的收货地址后，自动分离姓名、手机、省市区街道、详细门牌和邮编，降低人工录入错误率。
• 快递下单与物流面单：从一条原始文本中提取各个字段，用于打印面单或对接快递公司接口。
• CRM客户资料清洗：将历史积累的“地址+联系方式”混用字段拆解为结构化字段，便于后续统计分析。
• 办公地址入库：企业采购或供应商管理的地址信息，从自由文本标准化为数据库中的省、市、区、街道等独立列。

以上场景的共同特点是：输入字符串长度有限、格式不固定、但包含的语义要素（姓名、电话、邮编、省市）基本固定。采用一套稳定的地址解析服务，可以极大减少定制正则的维护维护复杂度。

接口能力边界

该接口名为“中文地址解析”，内部由纯本地正则算法实现，无外部上游依赖，单次请求为毫秒级响应。其核心能力包括：

1. 支持34个省级行政区及其简称：如“北京”会被解析为“北京市”，“新疆”解析为“新疆维吾尔自治区”。
2. 自动提取姓名、手机、邮编：输入中即使姓名和手机紧挨在一起（如“张三138xxxxxxxx”），也能正确分离。手机号会脱敏显示（中间四位替换为*）。
3. 省/市/区/街道四级拆分：对常见的市级、区县级和街道级名称识别较为准确，但需注意部分非常规行政名或别名可能无法覆盖（以具体返回为准）。
4. 输入长度限制：address 字段最大支持 500 字符，一条地址字符串的超长场景应做截断处理。
5. QPS限制：20次/秒；未添加 Authorization 头的匿名请求受更严格的流控。

需要强调：该接口基于规则模型，不含机器学习推理，因此对于写法极其不规范的地址（如缺失省、市层级直接写区名）可能降低识别率。返回结构可能不会拆分到門牌号，而是将“科苑路88号”整体作为 detail 字段。

参数与鉴权

请求方式

• URL：https://v1.apizero.cn/api/address-parse
• Method：POST
• Content-Type：application/json

Headers

请求体（JSON对象）

唯一必填字段：address，类型 string，长度 ≤ 500。示例：

{ "address": "张三 13812345678 上海市浦东新区张江镇科苑路88号 201203" }

代码接入：curl 示例

以下示例使用 Bash curl 发送请求，需要将$APIZERO_API_KEY替换为实际 API Key（可在控制台获取）。若在开发期测试匿名调用，可去掉-H "X-API-Key: ..."，但需注意限流。

curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"address": "张三 13812345678 上海市浦东新区张江镇科苑路88号 201203"}' \ "https://v1.apizero.cn/api/address-parse"

如果使用Authorization方式，可将 Header 改为-H "Authorization: Bearer sk_live_xxx"（具体格式以文档为准）。返回结果如下：

{ "code": 0, "data": { "city": "上海市", "detail": "科苑路88号", "district": "浦东新区", "name": "张三", "original": "张三 138****1234 上海市浦东新区张江镇科苑路88号 201203", "phone": "138****1234", "province": "上海市", "street": "张江镇", "zipcode": "201203" }, "msg": "成功", "request_id": "kx8n9q2a1b3c4d5e6f7g" }

Python 代码示例

对于不依赖 curl 的开发者，可以使用requests库（需预先安装）。注意将 API Key 替换。

import requests import json url = "https://v1.apizero.cn/api/address-parse" headers = { "X-API-Key": "your_api_key_here", # 或使用 "Authorization": "Bearer sk_live_xxx" "Content-Type": "application/json" } payload = {"address": "李四 13987654321 北京市海淀区中关村大街1号 100080"} try: resp = requests.post(url, headers=headers, json=payload, timeout=5) resp.raise_for_status() result = resp.json() print(json.dumps(result, indent=2, ensure_ascii=False)) except requests.exceptions.RequestException as e: print(f"请求异常: {e}")

返回值解读

响应是一个 JSON 对象，最外层包含code、msg、data、request_id。

• code: 整数，0 表示成功；非0 表示错误。
• msg: 字符串，描述信息。
• request_id: 字符串，每次请求的唯一标识，可用于排查问题。
• data: 解析结果对象，字段如下：

注意：若输入地址中包含多个姓名或电话，算法默认取第一个出现的。对于复杂歧义（如“张王村”可能被误认为姓名），需结合业务逻辑进一步判断。

常见错误与处理

工程化注意事项

1. 批量处理与限流：如果需要一次解析大量地址，应当采用请求队列 + 间隔控制，避免触发 429。建议每秒不超过 20 次。可以使用asyncio+aiohttp做并发，但需做好退避策略。
2. 数据缓存：相同的地址字符串可能会重复调用（如用户多次修改地址）。可在应用层增加 LRU 缓存，减少重复请求。缓存 key 可以使用 address 的哈希值。
3. 超时设置：网络请求应设定合理的超时时间（如 3-5 秒），防止接口抖动导致线程阻塞。
4. 结果后处理：返回的detail字段可能还包含房间号、楼层等信息，如需进一步拆分，可借助其他规则。同时，姓名与手机也可能存在于 detail 中（如果用户把姓名放在地址末尾），但算法会根据模式匹配尽量提取。建议对返回结果的空值做二次校验。
5. 日志与监控：记录每次请求的request_id、耗时、返回 code，方便故障回溯。为错误（如 429、500）建立告警。
6. 脱敏合规：接口默认对手机号做了脱敏，但业务系统在存储时可能还需要处理身份证号等其他敏感信息。注意不要将原始完整手机号存储到日志中。
7. 测测试例覆盖：编写单元测试，包含直辖市、普通省份、带简称的地址、无邮编、无姓名等边界情况。例如输入“广东省广州市天河区体育西路100号 王五 13600000000”，期望正确拆分 city 为“广州市”、district 为“天河区”、name 为“王五”。

参考文档

• 接口官方文档：https://apizero.cn/aidocs/address-parse（包含完整参数说明）
• 原始 Markdown 文档：https://apizero.cn/aidocs/address-parse/raw.md

（本文所有接口参数均来自上述文档，请以文档为最终参考。）