适用场景中文地址解析接口的核心能力是传入一段包含姓名、手机号、地址、邮编的混合字符串返回拆分后的结构化字段。在电商订单处理、快递面单打印、CRM 客户资料清洗、办公地址入库等场景中人工拆分地址耗时且容易出错用接口做自动化预处理可以显著提升效率。典型的输入形态包括张三 13812345678 上海市浦东新区张江镇科苑路88号 201203北京市海淀区中关村大街1号 李四 13900001111新疆乌鲁木齐市天山区解放路100号接口采用纯本地正则算法无上游依赖响应在毫秒级。需要说明的是这里的“无上游依赖”指的是服务端解析过程中不依赖第三方地址库具体响应延迟请以实际环境为准。接口能力边界在接入前需要明确这个接口能做什么、不能做什么支持 34 个省级行政区及其简称识别例如“北京”归一化为“北京市”“新疆”归一化为“新疆维吾尔自治区”。支持姓名、手机、邮编的混合输入提取但手机号和邮编会做脱敏处理例如响应中的phone为138****1234。地址长度限制为 500 字符超出后建议截断或做前置校验。返回字段固定省份、城市、区县、街道、详细地址、姓名、手机号、邮编、原始文本。QPS 限制为 20/s未登录匿名调用会受到更严格的限流具体阈值以文档为准。如果业务中需要处理非常规地址如“xx路xx号xx栋xx室”和“xx村xx组”混合建议先用样本数据做充分测试确认解析结果符合预期。请求参数与鉴权请求方法与地址请求方法POST请求地址https://v1.apizero.cn/api/address-parse请求头Content-Type: application/jsonHeader 参数参数名是否必须类型说明Authorization否stringBearer sk_live_xxx可选未登录匿名调用受更严格限流X-API-Key视文档而定string部分调用方式使用该头部传递密钥请以文档页说明为准素材中的 curl 示例使用了X-API-Key作为鉴权头同时接口文档也支持Authorization: Bearer sk_live_xxx的方式。建议在代码中固定一种鉴权方式将密钥放到环境变量中避免硬编码。请求体字段请求体是一个 JSON 对象只有一个必填字段address。字段类型是否必须说明addressstring是中文地址字符串支持姓名/手机/邮编混合输入长度 ≤ 500请求体示例{ address: 张三 13812345678 上海市浦东新区张江镇科苑路88号 201203 }如果传入空字符串或非 string 类型接口会返回错误。建议客户端在发起请求前先做类型和长度检查避免无效请求消耗 QPS。使用 curl 接入以下是一个可直接运行的 curl 示例请将$APIZERO_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头可以这样写curl -sS \ -X POST \ -H Authorization: Bearer sk_live_xxx \ -H Content-Type: application/json \ -d {address: 新疆乌鲁木齐市天山区解放路100号} \ https://v1.apizero.cn/api/address-parse注意上面示例中的sk_live_xxx是占位符你需要替换成自己账号下的真实密钥。生产环境推荐使用环境变量export APIZERO_API_KEYsk_live_your_key然后通过$APIZERO_API_KEY引用。响应字段解读成功响应的Content-Type为application/json外层结构固定为code、msg、data、request_id。{ code: 0, data: { city: 上海市, detail: 科苑路88号, district: 浦东新区, name: 张三, original: 张三 138****1234 上海市浦东新区张江镇科苑路88号 201203, phone: 138****1234, province: 上海市, street: 张江镇, zipcode: 201203 }, msg: 成功, request_id: kx8n9q2a1b3c4d5e6f7g }data 字段明细字段类型说明provincestring省份已做归一化如“上海市”citystring城市如“上海市”districtstring区县如“浦东新区”streetstring街道/乡镇如“张江镇”detailstring剩余详细地址如“科苑路88号”namestring识别出的姓名phonestring脱敏后的手机号zipcodestring邮编originalstring原始字符串手机号已脱敏注意original字段中的手机号被中间四位替换为****这是接口的脱敏处理。如果你需要原始手机号接口不返回请勿将明文手机号写入日志。street字段在输入没有明确乡镇/街道时会返回空字符串或缺失需要根据实际响应处理。常见错误排查这里列出几类常见问题实际错误码与错误信息请以接口返回为准。1. 鉴权失败现象返回code非 0或 HTTP 状态码为 401/403。排查检查X-API-Key或Authorization是否正确密钥是否过期是否在请求头中正确携带。2. 请求体格式错误现象接口无法解析 JSON返回格式错误。排查确保Content-Type为application/json请求体是合法的 JSON 对象字段名address必须存在字符串用双引号。3. 地址长度超限现象address长度超过 500 字符。排查在客户端预处理超过 500 字符的地址可以先截断或拆分也可以在业务层设置更保守的长度上限比如 200 字符。4. 解析不到姓名或手机号现象返回的name或phone为空。排查确认输入的字符串中确实包含姓名和手机号手机号必须是 11 位数字如果隐私要求可以用x或*占位但接口可能无法提取。5. QPS 限流现象短时间内大量请求被拒绝。排查控制调用频率不要超过 20/s如果需要更高并发考虑使用Authorization鉴权方式若有更高权益以文档为准。工程化注意事项超时与重试接口是网络请求必须设置合理的超时时间。建议连接超时3 秒读取超时5 秒重试策略对超时和 5xx 错误做重试最多重试 2 次并使用指数退避如 200ms、400ms。日志脱敏original字段包含脱敏后的手机号但address请求参数中的手机号是明文。建议请求日志不打印完整address只打印长度或截断后的前 20 个字符。响应日志中直接使用接口返回的original字段不要拼接请求参数。数据校验与兜底接口返回的province、city等字段不一定完全符合你们系统的字典。建议在入库前做一次映射校验例如# 示例将接口返回的省份名映射到业务字典 province_map { 上海市: 上海, 新疆维吾尔自治区: 新疆, } standard_province province_map.get(data.get(province), data.get(province))如果detail为空可以用streetdetail的逻辑拼接完整地址但要避免重复拼接。批量处理限制接口一次只能解析一个地址没有批量接口。若需要批量清洗建议在本地做并发控制用线程池或异步队列限制并发数避免触发限流。测测试例设计建议准备以下测试样本标准带姓名手机号邮编的地址。只有地址没有手机号。省级简称输入如“北京”“新疆”。地址中夹杂英文或特殊符号。地址长度接近 500 字符。用这些样本跑一遍确认解析结果是否符合预期。如果个别地址解析错误可以考虑在前置流程中用正则先清洗一次再调用接口。参考文档接口文档页https://apizero.cn/aidocs/address-parse原始 Markdown 文档https://apizero.cn/aidocs/address-parse/raw.md
)
