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

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

相关推荐
spencer_tseng11 分钟前
VideoConvertor.java ffmpeg.exe
java
○陈15 分钟前
js面试题|[2024-12-10]
java·前端·javascript
微服务技术分享27 分钟前
探店小程序：解锁商业新生态，定制未来
java·小程序·小程序搭建·探店小程序搭建
寒山李白31 分钟前
Nignx部署Java服务测试使用的Spring Boot项目Demo
java·开发语言·spring boot
狄加山67534 分钟前
C语言(函数)
java·c语言·算法
程序猿进阶1 小时前
可视化逻辑表达式编辑器
java·spring boot·后端·面试·性能优化·架构·编辑器
E___V___E1 小时前
计算机组成原理复习
java·开发语言
武子康1 小时前
Java-23 深入浅出 MyBatis - 手写ORM框架4 框架优化 SqlSession DefaultSqlSession
java·开发语言·sql·mybatis·springboot
Matrix701 小时前
Java_实例变量和局部变量及this关键字详解
java·开发语言
神洛华1 小时前
Y3编辑器文档4：触发器1（对话、装备、特效、行为树、排行榜、不同步问题）
java·开发语言·编辑器
热门推荐
01(欧拉)openEuler系统添加网卡文件配置流程、(欧拉)openEuler系统手动配置ipv6地址流程、(欧拉)openEuler系统网络管理说明02【halcon】halcon字符识别——OCR03玄机平台应急响应—webshell查杀04【一文读懂】NTN（非地面网络）技术介绍0504 - matlab m_map地学绘图工具基础函数 - 设置网格06Docker 夺命连环 15 问07『手写ahooks系列-useClickAway』一个hook解决监听点击元素外部08支付宝短视频平台创作分成激励项目09PyTorch机器学习实现液态神经网络10校验 GPT-4 真实性的三个经典问题：快速区分 GPT-3.5 与 GPT-4，并提供免费测试网站