快递智能地址解析API接口对接实现指南

码农阿豪2024-12-12 8:49

目录

快递智能地址解析API接口对接实现指南

随着电商和物流行业的快速发展，地址解析已成为提高效率和优化用户体验的重要技术手段。本文将详细介绍快递100智能地址解析API的功能、应用效果以及对接实现过程，帮助开发者快速上手。

一、智能地址解析接口介绍

快递100智能地址解析接口，是一款高效地址解析服务。

它可以精准识别输入内容中的 姓名、电话、地址 等关键信息，并将杂乱无序的地址数据纠错、补全和标准化，输出为结构化的地址信息：

plaintext 复制代码 
格式
省 - 市 - 区 - 详细地址
例如
浙江省 杭州市 滨江区 长河街道春波小区*幢*单元***号

功能亮点

  1. 文本与图片解析：支持文本与图片两种输入形式，方便灵活。
  2. 地址自动补全：对缺失字段（如省市区）进行智能补全，确保地址完整性。
  3. 纠错与优化：自动纠正常见错别字或错误地址描述。
  4. 高效对接：简单易用的接口，适配多种开发环境。

二、应用场景与效果

通过快递100智能地址解析API，用户能够在地址录入场景中更加高效地填写订单信息，尤其适用于个人地址薄管理和寄件操作。以下是具体应用效果：

结构化输出

输入任意格式的地址信息后，API将其按 省-市-区-详细地址 的标准格式输出，减少手动录入带来的失误，显著提升录入效率。

关键信息提取

能够精准提取寄件人或收件人信息中的 联系方式和姓名，并自动生成结构化数据，免去人工整理的麻烦，进一步降低错误率。

地址补全

结合 地图POI数据，在用户地址填写中自动补全缺失的地理位置信息，如门牌号或具体地点。用户可通过搜索地址坐标快速生成完整的地址，提升填写效率。

错误纠正与优化

针对用户输入的错误地址（如省、市、区字段），API提供智能纠正功能，确保下单信息完整、准确，有效避免因地址不全或错误导致的揽派问题。

这项技术为用户提供了高效、便捷的地址管理能力，同时帮助企业优化物流流程，提高订单的处理质量。

三、接口测试与对接指南

在对接快递100智能地址解析API前，我们需要完成以下步骤：

1. 注册与获取API Key

2. 智能地址解析接口

该接口提供智能识别姓名、电话、地址的功能，并解析地址返回对应信息。

1.1 接口格式

提供统一格式的 HTTP POST 调用接口，并返回统一格式的 JSON 数据。

1.2 请求地址
java 复制代码 
https://api.kuaidi100.com/address/resolution
请求参数（header）：
参数名 类型 默认值
Content-Type string application/x-www-form-urlencoded
请求参数（body）：
参数名 是否必填 类型 说明
key 是 string 授权码，请申请企业版获取
sign 是 string 32 位大写签名，用于验证身份，按 MD5(param + t + key + secret) 的顺序加密，不需要加上 "+" 号，secret 在企业管理后台查看
t 是 string 时间戳，如：1576123932000
param 是 param 由其他字段拼接
param 数据结构：
参数名 是否必填 类型 说明
content 否 string 需要解析的内容，例如：张三广东省深圳市南山区粤海街道科技南十二路金蝶软件园13088888888
image 否 string 图片 base64 编码，最大限制 4M
imageUrl 否 string 图片 URL，通过该 URL 下载后得到的文件文件类型应当是图片，最大限制 4M
pdfUrl 否 string PDF URL，通过该 URL 下载后得到的文件文件类型应当是 PDF，最大限制 4M
htmlUrl 否 string HTML URL，通过该 URL 下载后得到的文件文件类型应当是 HTML，最大限制 4M

注意： 接口超时为 5 秒。content、image、imageUrl、pdfUrl、htmlUrl 必填其一，优先顺序为：content > image > imageUrl > pdfUrl > htmlUrl。

1.3 返回结果
字段 类型 说明 备注
success boolean 提交结果 true 提交成功，false 失败
code string 返回编码
message string 返回报文描述
time string 时间 可忽略
data Object 响应数据
data 数据结构：
字段 类型 说明 备注
taskId string 任务 ID
result list 解析结果列表
result 中数据项的数据结构：
字段 类型 说明 备注
content string 入参的解析内容
mobile list 手机号码列表 列表中的手机号码为字符串格式
name string 姓名
address string 详细地址
xzq object 行政区信息
xzq 中数据项的数据结构：
字段 类型 说明 备注
fullName string 完整地址 返回省市区全称，例如：广东省,深圳市,南山区
province string 省份名称 返回省份简称，例如：广东
city string 城市名称 返回市级行政区简称，例如：深圳市
district string 区县名称 返回区县简称，例如：南山区
subArea string 详细地址
parentCode string 行政区父节点编码
code string 行政区编码
level int 行政区级别
1.4 请求参数示例
示例1
json 复制代码 
key = kytRstexx
sign = 4BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
    "content": "张三广东省深圳市南山区粤海街道科技南十二路金蝶软件园13088888888"
}
示例2
json 复制代码 
key = kytRstexx
sign = 4BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
    "imageUrl": "https://api.kuaidi100.com/getImage/123456789"
}
1.5 返回结果示例
成功示例
json 复制代码 
{
    "code": 200,
    "data": {
        "taskId": "0333CB76E70442A0BD275F5541549C30",
        "result": [
            {
                "content": "张三广东省深圳市南山区粤海街道科技南十二路金蝶软件园 13088888888",
                "mobile": [
                    "13088888888"
                ],
                "name": "张三",
                "address": "粤海街道科技南十二路金蝶软件园",
                "xzq": {
                    "fullName": "广东省,深圳市,南山区",
                    "province": "广东",
                    "city": "深圳市",
                    "district": "南山区",
                    "subArea": "粤海街道科技南十二路金蝶软件园",
                    "parentCode": "440300",
                    "code": "440305",
                    "level": 3
                }
            }
        ]
    },
    "message": "success",
    "time": 0,
    "success": true
}
错误示例
json 复制代码 
{
   "code":10002,
   "message":"请求参数不能为空：content",
   "time":0,
   "success":false
}
1.6 返回信息代码含义
信息代码 信息内容描述 原因及建议处理方式
-1 解析失败/异常，请稍后重试 快递100的服务器出现间歇或临时性异常，解析超时，也会报此错误
200 提交成功 提交成功
10000 解析失败 解析失败，请检查入参内容是否正确
10002 请求参数错误 检查参数传参是否正确
10007 系统内部调用异常 系统内部调用异常，文件识别结果为空、识别失败、解析失败，请联系管理员处理
10025 非法请求，异常文件 接口请求下载文件识别报错会报此错误，请检查文件（URL 中的文件）是否完整、格式是否正确
30002 验证签名失败 检查加密方式，param +t+key+ secret 的顺序进行 MD5 加密，加密后字符串转 32 位大写，不用加上"+"号
30004 账号单量不足需要充值 账号单量不足需要充值

3. java示例代码 （直接拿去用）

以下是两种场景的整合测试对接示例：

测试代码
java 复制代码 
public class AddressResolutionTest {

    // 替换为实际的 key 和 secret，来源于快递100管理后台 - 我的信息 - 企业信息
    private static final String KEY = "kJg******63";
    private static final String SECRET = "957**********************f58";
    private static final String API_URL = "https://api.kuaidi100.com/address/resolution";

    public static void main(String[] args) throws Exception {
        testTextParsing();
        testImageParsing();
    }

    // 文本解析测试
    public static void testTextParsing() throws Exception {
        String content = "张三广东省深圳市南山区粤海街道科技南十二路金蝶软件园13088888888";
        Map<String, Object> param = new HashMap<>();
        param.put("content", content);

        String response = sendRequest(param);
        System.out.println("文本解析响应：" + response);
    }

    // 图片解析测试
    public static void testImageParsing() throws Exception {
        String imageUrl = "https://ahaofile-1304457300.cos.ap-guangzhou.myqcloud.com/kuaidi100.png";
        Map<String, Object> param = new HashMap<>();
        param.put("imageUrl", imageUrl);

        String response = sendRequest(param);
        System.out.println("图片解析响应：" + response);
    }

    // 发送请求
    private static String sendRequest(Map<String, Object> param) throws Exception {
        // 时间戳
        String timestamp = String.valueOf(System.currentTimeMillis());
        // 参数 JSON 字符串
        String paramJson = new ObjectMapper().writeValueAsString(param);
        // 生成签名
        String sign = generateMD5(paramJson + timestamp + KEY + SECRET);

        // 构造请求参数
        Map<String, String> body = new HashMap<>();
        body.put("key", KEY);
        body.put("sign", sign);
        body.put("t", timestamp);
        body.put("param", paramJson);

        // 发送 POST 请求
        return post(API_URL, body);
    }

    // 生成 MD5
    private static String generateMD5(String input) throws Exception {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] digest = md.digest(input.getBytes(StandardCharsets.UTF_8));
        StringBuilder sb = new StringBuilder();
        for (byte b : digest) {
            sb.append(String.format("%02X", b));
        }
        return sb.toString();
    }

    // 发送 POST 请求
    private static String post(String url, Map<String, String> body) throws Exception {
        try (CloseableHttpClient client = HttpClients.createDefault()) {
            HttpPost post = new HttpPost(url);
            post.setHeader("Content-Type", "application/x-www-form-urlencoded");

            // 构造请求体
            StringBuilder formData = new StringBuilder();
            for (Map.Entry<String, String> entry : body.entrySet()) {
                if (formData.length() > 0) {
                    formData.append("&");
                }
                formData.append(entry.getKey()).append("=").append(entry.getValue());
            }
            post.setEntity(new StringEntity(formData.toString(), StandardCharsets.UTF_8));

            // 执行请求
            try (CloseableHttpResponse response = client.execute(post)) {
                HttpEntity entity = response.getEntity();
                return entity != null ? EntityUtils.toString(entity, StandardCharsets.UTF_8) : null;
            }
        }
    }
}
场景一：识别文本地址信息 测试结果

测试文本

text 复制代码 
张三广东省深圳市南山区粤海街道科技南十二路金蝶软件园13088888888
json 复制代码 
文本解析响应：
{
	"code": 200,
	"data": {
		"taskId": "840225995A8E4576B56BEBDD5B308D40",
		"result": [
			{
				"content": "张三广东省深圳市南山区粤海街道科技南十二路金蝶软件园13088888888",
				"mobile": [
					"13088888888"
				],
				"name": "张三",
				"address": "粤海街道科技南十二路金蝶软件园",
				"xzq": {
					"fullName": "广东省,深圳市,南山区",
					"province": "广东",
					"city": "深圳市",
					"district": "南山区",
					"subArea": "粤海街道科技南十二路金蝶软件园",
					"parentCode": "440300",
					"code": "440305",
					"level": 3
				}
			}
		]
	},
	"message": "success",
	"time": 0,
	"success": true
}
场景二：识别图片中的地址信息 测试结果

图片已传入腾讯云COS，可直接使用

json 复制代码 
图片解析响应：
{
	"code": 200,
	"data": {
		"taskId": "B02798CABE7F4A69994C4079D1691D34",
		"result": [
			{
				"content": "阿豪15288888888浙江省杭州市滨江区长河街道春波小区六幢六单元666",
				"mobile": [
					"15288888888"
				],
				"name": "阿豪",
				"address": "长河街道春波小区六幢六单元666",
				"xzq": {
					"fullName": "浙江省,杭州市,滨江区",
					"province": "浙江省",
					"city": "杭州市",
					"district": "滨江区",
					"subArea": "长河街道春波小区六幢六单元666",
					"parentCode": "330100",
					"code": "330108",
					"level": 3
				}
			}
		]
	},
	"message": "success",
	"time": 0,
	"success": true
}

四、总结

快递100智能地址解析API通过其强大的文本和图片解析能力，为电商和物流行业提供了标准化地址管理的高效解决方案。

通过本文的指南，相信您可以快速完成接口对接，并利用这项技术提升用户体验和业务效率。

相关推荐
需要8265 小时前
Spring Bean 生命周期：从实例化到销毁的完整钩子
java·后端·spring
小 黄 鸡5 小时前
HashMap 面试必会知识点详解（JDK 8）
java·面试·职场和发展
伯恩bourne7 小时前
Spring Boot Bean 注册的两种方式：@Component 家族 vs @Configuration + @Bean
java·spring boot·后端
silvamux_7 小时前
curl 测试 OpenAI 兼容 API 的完整流程
java·人工智能·缓存·ai·oneapi
省钱兄--zs8 小时前
深圳24小时自助健身房软硬件解决方案实战指南与开发流程详解
java·数据仓库·spring boot·小程序·架构
顽疲8 小时前
Java vue 养老系统源码详解：月账单 care_month_bill 与 Quartz 扣费 Job 实践
java·开发语言·vue.js·vue养老·springboot养老·java养老
Wang's Blog8 小时前
Java 项目实战: 交友项目 - 安装开发工具与环境准备
java·开发语言·交友
用户21296835261688 小时前
开源了一个 Java 多智能体 LLM 框架 Baton：一个依赖，把 Agent 循环、工具调用、记忆、编排全配齐
java·llm
helmsail8 小时前
05 管理活动与选品
java
天远数科9 小时前
Java数据工程：利用天远人车核验加强版优化智慧高速ETC发行合规体验
java·人工智能
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02「全语录+省流版」邵艾伦 × 孙宇晨：聊风口、聊个人IP、聊年轻人如何抓住 AI 时代的机会03历年考研数学一、数学二、数学三真题试卷及答案PDF04GitHub 镜像站点05几个好用的ip纯净度检测网站06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07Telegram APK 下载安装完整指南 — 2026年最新08Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）09微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新10轻量化AI渗透武器库｜ARTEX自主攻防系统、资产梳理、漏洞挖掘、链路分析全流程智能化落地