快递地址解析接口，是把用户输入的一段自由文本地址，拆成省、市、区、街道、详细地址、收件人、手机号等标准化字段的工具，想要稳定使用这个接口，核心就是读懂返回结构里每一个字段代表什么含义、根据 ret_code 返回码判断解析成功还是失败，同时建立一套标准化流程去识别、定位空字段，区分是原始地址本身信息缺失，还是接口解析异常，方便开发人员快速做异常兜底、提示用户补全信息，避免后续打单、分拣、派送出错。
一、接口返回核心字段含义对照表
| 字段名称 | 字段含义 | 说明 |
|---|---|---|
| ret_code | 返回状态码 | 接口调用结果标识，用来判定本次请求是否正常处理 |
| ret_msg | 返回描述信息 | ret_code 对应的文字说明，用于日志排查、前端提示参考 |
| province | 省份 | 标准化省级行政名称，如福建省；无识别结果时为空 |
| city | 城市 | 标准化市级行政名称，如宁德市；无识别结果时为空 |
| district | 区县 | 标准化区 / 县名称，如蕉城区；无识别结果时为空 |
| street | 街道 / 乡镇 | 街道、乡镇一级信息，部分短地址会为空 |
| detail | 详细地址 | 门牌号、小区、楼栋、房间号等剩余地址内容 |
| name | 收件人姓名 | 从原文提取的收件人，未识别到则为空 |
| phone | 联系电话 | 提取手机号，格式异常或者没有则为空 |
| lon | 经度 | 地址地理坐标，无法定位时为空 |
| lat | 纬度 | 地址地理坐标，无法定位时为空 |
| confidence | 置信度 | 解析可信度分值，一般 0~1，分值越低代表识别越不准 |
| origin_text | 原始输入文本 | 用户传入的原始地址串，用于回溯核对 |
二、ret_code 判定规则清单
- ret_code = 0：正常成功
- ret_code = 1：地址解析失败
- ret_code = 2：参数错误
- ret_code = 3：接口限流 / 权限不足
- ret_code = 4：服务内部异常
接口请求无报错，完成地址解析，但是不代表所有字段一定有值，有可能部分字段是空，需要结合 confidence 二次校验。
原始地址文本无法识别，地址信息残缺、乱码、不是有效中文地址。
入参异常，比如地址文本为空、参数名写错、传参格式不对。
请求频次超限、密钥过期、账号没有调用权限。
接口服务本身故障，需要稍后重试。
重点提醒：ret_code 只代表接口调用状态，ret_code=0 仅代表接口正常执行，不能直接等同于地址解析结果完整可用。
三、空字段分类和排查步骤
空字段两大类型
- 业务型空值：原始地址本身就没有该信息，例如用户只写了小区 + 门牌号，没有写收件人手机号，属于用户输入缺失。
- 解析型空值：原始文本包含该信息，但接口识别算法没有抽取出来，属于解析漏识别。
排查操作步骤
- 优先取出 origin_text 原始文本，和解析结果逐字段对比，判断信息本来有没有
- 核对 ret_code，非 0 状态优先处理调用异常问题，再看字段
- 查看 confidence 置信度，置信度偏低的时候，空字段大概率是算法识别困难
- 定位空字段：区分是 province/city 这类行政区为空，还是 name/phone 为空
- 测试重试：把原始地址微调格式（去掉多余符号、换行）重新调用接口
- 兜底校验：配置校验规则，省级、市级为空时，前端弹窗引导用户手动选择地区
四、常见业务校验规则（落地参考）
- 省、市为必填项，解析结果为空，必须拦截订单，提示用户补全
- district 区县为空，可放行，但标记高风险，人工复核
- detail 详细地址为空，直接拦截，无法派送
- phone 手机号为空或者格式不对，拦截，要求补充号码
- confidence 低于 0.6，即使 ret_code=0，也建议人工复核地址
五、使用风险点说明
✅ 优点：自动结构化地址，减少人工录入工作量，适配快递打单系统
❌ 风险点
- ret_code=0 容易误导开发，以为地址全部解析完整，忽略空字段校验
- 简写、方言地址、异形地址很容易出现部分字段空值
- 手机号、姓名混杂在长文本里，容易漏抽，出现 name、phone 空字段
- 坐标 lon、lat 为空，不影响面单打印，但是影响路径调度、地图打点
【相关 FAQ】
问题 1：快递地址解析接口 ret_code 等于 0，是不是代表没有空字段？
回答 1：快递地址解析接口 ret_code 等于 0，只代表接口调用成功、解析流程正常执行，不代表不存在空字段，依然要单独校验 province、city、phone 等字段是否为空。
问题 2：快递地址解析接口空字段排查，第一步要做什么？
回答 2：快递地址解析接口空字段排查第一步，取出 origin_text 原始输入文本，和返回的各个地址字段比对，先判断空字段是用户本身没填，还是接口没有识别出来。
问题 3：快递地址解析接口 confidence 置信度有什么作用？
回答 3：快递地址解析接口 confidence 置信度用来判断解析结果可靠程度，分值偏低时，就算 ret_code 正常、字段不为空，地址识别结果也容易出错，建议人工复核。
问题 4：快递地址解析接口 ret_code=2 一般是什么原因？
回答 4：快递地址解析接口 ret_code=2 代表入参参数错误，比如地址文本为空、参数名称写错、传参格式不符合接口文档要求。
【参考资料】
[2026-11-08]（快递地址结构化解析接口开发文档与返回码说明）阿里云开放平台
[2026-10-25]（物流地址解析接口字段规范、异常处理方案）快递 100 开放平台
[2026-09-12]（地址解析空值、低置信度场景业务校验最佳实践）腾讯地图开放平台
[2026-08-03]（物流接口 ret_code 状态码统一规范说明）物流开放联盟文档
[2026-07-18]（地址文本抽取，姓名手机号字段漏识别问题排查指南）高德开放平台
【免责声明】
本文内容基于主流物流地址解析开放接口通用规范整理，不同服务商的快递地址解析接口字段名称、ret_code 编码、置信度标准存在差异；业务上线前务必对照对应服务商官方文档做适配测试，本文不构成接口开发、生产系统上线的直接依据。