@TOC

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

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

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

快递 100 智能地址解析接口，是一款高效地址解析服务。
它可以精准识别输入内容中的 姓名、电话、地址 等关键信息，并将杂乱无序的地址数据纠错、补全和标准化，输出为结构化的地址信息：

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

功能亮点

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

二、应用场景与效果

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

结构化输出

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

关键信息提取

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

地址补全

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

错误纠正与优化

针对用户输入的错误地址（如省、市、区字段），API 提供智能纠正功能，确保下单信息完整、准确，有效避免因地址不全或错误导致的揽派问题。
这项技术为用户提供了高效、便捷的地址管理能力，同时帮助企业优化物流流程，提高订单的处理质量。

三、接口测试与对接指南

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

1. 注册与获取 API Key

• 前往 快递 100API 开放平台 注册账号。
• 找客户经理添加智能地址解析测试单量，获取 API Key 和 Secret。
  可以参考我之前的这篇文章《快递 100 物流查询 API 全面解析》

2. 智能地址解析接口

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

1.1 接口格式

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

1.2 请求地址

https://api.kuaidi100.com/address/resolution

请求参数（header）：

请求参数（body）：

param 数据结构：

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

1.3 返回结果

data 数据结构：

result 中数据项的数据结构：

xzq 中数据项的数据结构：

1.4 请求参数示例

示例 1

key = kytRstexx
sign = 4BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
    "content": "张三广东省深圳市南山区粤海街道科技南十二路金蝶软件园13088888888"
}

示例 2

key = kytRstexx
sign = 4BBDE07660E5EFF90873642CFAE9A8DD
t = 1470304729724
param = {
    "imageUrl": "https://api.kuaidi100.com/getImage/123456789"
}

1.5 返回结果示例

成功示例

{
  "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
}

错误示例

{
  "code": 10002,
  "message": "请求参数不能为空：content",
  "time": 0,
  "success": false
}

1.6 返回信息代码含义

3. 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;
            }
        }
    }
}

场景一：识别文本地址信息 测试结果

测试文本

张三广东省深圳市南山区粤海街道科技南十二路金蝶软件园13088888888

文本解析响应：
{
	"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，可直接使用

图片解析响应：
{
	"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 通过其强大的文本和图片解析能力，为电商和物流行业提供了标准化地址管理的高效解决方案。
通过本文的指南，相信您可以快速完成接口对接，并利用这项技术提升用户体验和业务效率。