当前位置：首页 > news >正文

最小可运行示例：中文地址解析API请求与响应字段全解析

news 2026/7/24 2:54:27

适用场景

电商收货地址自动拆分、快递下单页智能填充、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联系技术支持