快宝开放平台地址清洗 api 接口文档

API 文档 /
地址库服务 /
地址清洗
应用场景
1. 电商平台、电商 ERP、物流应用等需要对客户输入的地址信息进行清洗、识别,转化为包含省、市、区、乡镇街道、详细地址等结构化信息

  1. 需要将包含了不规范的行政区域名称、过时的旧称呼、已经撤销或合并的行政区域名称的地址,转化为规范、最新、准确的行政区域名称

  2. 给定的地址不完整,需要补全省、市、区县、乡镇等信息

主要功能
1. 将包含地址信息的文本,识别为结构化的地址信息,返回省、市、区、乡镇、详细地址等分段信息,能够智能补全缺失的行政区域,过滤掉重复、冗余信息

  1. 对于包含了不规范的行政区域名称、过时的旧称呼、已经撤销或合并的行政区域名称的地址,可以通过该接口解析为规范、最新、准确的行政区域名称

  2. 返回行政区域全称、简称、代码等详细信息

额外说明
技术咨询请加微信:kuaibao135

接口名称
cloud.address.cleanse

公共参数
请求地址
环境名称 HTTPS 请求地址
正式地址 https://kop.kuaidihelp.com/api
公共请求参数
名称 类型 是否必须 描述
method string 是
API 接口名称
app_id string 是
用户 ID(注册开放平台时分配,在控制台中查看)
sign string 是
按照规则 (md5(app_id + method + ts + api_key)) 生成的合法性验证签名 (32 位字符串,字母小写) 如:10000cloud.print.do1524209949bdf3b5f50865ac813cbdfd6c9b572b79 加密后 5030cae3388ecdc2e686379753a0564c
ts string 是
当前请求的时间戳 (10 位或 13 位)
data string 是
JSON 格式请求参数
公共响应参数
名称 类型 是否必须 描述
code int 是
响应状态码。0- 成功,非 0- 失败下载并查看详情
msg string 是
返回结果说明
uid string 是
本次请求唯一业务流水号
data string 是
JSON 格式响应数据
请求参数
名称 类型 是否必须 描述
text string 是
包含地址信息的文本,批量模式下多条地址用回车或换行符(\r 或 \n)分隔
multimode bool 否
是否为批量模式,false 为非批量,此时整个 text 参数认为是一条地址;true 为批量,此时根据 text 参数中的换行符区隔多条地址。默认为 true
cleanTown int 否
是否从地址中清洗乡镇、街道级别行政区域信息。0:不清洗,1:地址中包含有乡镇、街道名称,则清洗,否则不清洗,2:不管地址中是否包含乡镇、街道名称,都尝试清洗乡镇信息。默认值为 0。若值为 1 或 2,返回结果中会包含 town,town_id, town_code 字段,address 字段中将不再包含乡镇级别行政区域信息
响应参数
名称 类型 是否必须 描述
province string 是
省级名称。响应体的 data 字段为一数组,每个数组元素为一条解析结果,本节描述的是每个元素的字段
province_id string 是
省级快宝编号
province_code string 是
省级行政编码
province_shortname string 是
省级简称
city string 是
市级名称
city_id string 是
市级快宝编号
city_code string 是
市级行政编码
city_shortname string 是
市级简称
county string 是
县级名称
county_id string 是
县级快宝编号
county_code string 是
县级行政编码
county_shortname string 是
县级简称
town string 否
乡镇名称 (只有 cleanTown=True 时, 才有值返回)
town_id string 否
乡镇快宝编号 (只有 cleanTown=True 时, 才有值返回)
town_code string 否
乡镇行政编码 (只有 cleanTown=True 时, 才有值返回)
address string 是
详细地址
original string 是
输入的原始文本
res string 是
是否返回完整结果
address string 是
详细地址
original string 是
输入的原始文本
res string 是
是否返回完整结果
province_confidence int 是
省级信息解析准确度字段,当返回值小于 3 时认为准确度相对较低有识别错误概率,该字段可用于客户端提示用户检查地址信息时使用;
city_confidence int 是
市级信息解析准确度字段,当返回值小于 3 时认为准确度相对较低有识别错误概率,该字段可用于客户端提示用户检查地址信息时使用;
county_confidence int 是
区级信息解析准确度字段,当返回值小于 3 时认为准确度相对较低有识别错误概率,该字段可用于客户端提示用户检查地址信息时使用;
请求示例
Java
C#
Python
PHP
Node.js
Curl
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

import java.util.Map;
import java.util.HashMap;

import java.util.Date;

public class Request {

public static void main(String[] args) {
String host = “http://kop.kuaidihelp.com”;
String path = “/api”;
String requestMethod = “POST”;
Map<String, String> headers = new HashMap<String, String>();
// 根据 API 的要求,定义相对应的 Content-Type
headers.put(“Content-Type”, “application/x-www-form-urlencoded; charset=UTF-8”);
Map<String, String> querys = new HashMap<String, String>();
Map<String, String> bodys = new HashMap<String, String>();

String appId = “50001”;
String method = “cloud.address.cleanse”;
// 当前时间戳
String ts = new Date().getTime() + "";
String appKey = “bdf3b5f50865ac813cbdfd6c9b572b79”;

// 计算签名
String signStr = appId + method + ts + appKey;
String sign = Request.getMD5(signStr, 32);

bodys.put(“app_id”, appId);
bodys.put(“method”, method);
bodys.put(“ts”, ts);
bodys.put(“sign”, sign);
// data 参数是个 json 格式的字符串 建议使用函数或方法去生成
bodys.put(“data”, “{
“multimode”:true,
“address”:” 广东省梅州市五华县安流镇青江村琴江御城 201 商场 \r 深圳市龙华新区观澜街道库坑新围村皇帝印工业区 D 栋 \r 杭州市中河中路 258 号瑞丰国际商务大厦 5F",
“cleanTown”:true
}");

try {
/**
* 重要提示如下:
* HttpUtils 请从
* https://github.com/aliyun/api-gateway-demo-sign-java/blob/master/src/main/java/com/aliyun/api/gateway/demo/util/HttpUtils.java
* 下载
*
* 相应的依赖请参照
* https://github.com/aliyun/api-gateway-demo-sign-java/blob/master/pom.xml
*/
HttpResponse response = HttpUtils.doPost(host, path, requestMethod, headers, querys, bodys);
System.out.println(response.toString());

	//获取response的body
	System.out.println(EntityUtils.toString(response.getEntity()));
} catch (Exception e) {
	e.printStackTrace();
}

}

// 计算md5
public static String getMD5(String plainText, int length) {
    try {
        MessageDigest md = MessageDigest.getInstance("MD5");//获取MD5实例
        md.update(plainText.getBytes());//此处传入要加密的byte类型值
        byte[] digest = md.digest();//此处得到的是md5加密后的byte类型值

        /*
           下边的运算就是自己添加的一些二次小加密,记住这个千万不能弄错乱,
               否则在解密的时候,你会发现值不对的(举例:在注册的时候加密方式是一种,
            在我们登录的时候是不是还需要加密它的密码然后和数据库的进行比对,但是
        最后我们发现,明明密码对啊,就是打不到预期效果,这时候你就要想一下,你是否
         有改动前后的加密方式)   
        */
        int i;
        StringBuilder sb = new StringBuilder();
        for (int offset = 0; offset < digest.length; offset++) {
            i = digest[offset];
            if (i < 0)
                i += 256;
            if (i < 16)
                sb.append(0);
            sb.append(Integer.toHexString(i));//通过Integer.toHexString方法把值变为16进制
        }
        return sb.toString().substring(0, length);//从下标0开始,length目的是截取多少长度的值
    } catch (NoSuchAlgorithmException e) {
        e.printStackTrace();
        return null;
    }
}

}
响应示例
成功响应示例
JSON 示例
{
“code”:int0
“msg”:string"成功"
“data”:[
0:{
“original”:string"广东省梅州市五华县安流镇青江村琴江御城 201 商场"
“province”:string"广东省"
“province_id”:string"5876"
“province_code”:string"440000"
“province_shortname”:string"广东"
“city”:string"梅州市"
“city_id”:string"6068"
“city_code”:string"441400"
“city_shortname”:string"梅州"
“county”:string"五华县"
“county_id”:string"6077"
“county_code”:string"441424"
“county_shortname”:string"五华"
“town”:string"安流镇"
“town_id”:string"906952"
“town_code”:string""
“address”:string"青江村琴江御城 201 商场"
}
1:{
“original”:string"深圳市龙华新区观澜街道库坑新围村皇帝印工业区 D 栋"
“province”:string"广东省"
“province_id”:string"5876"
“province_code”:string"440000"
“province_shortname”:string"广东"
“city”:string"深圳市"
“city_id”:string"5947"
“city_code”:string"440300"
“city_shortname”:string"深圳"
“county”:string"龙华区"
“county_id”:string"882409"
“county_code”:string"460106"
“county_shortname”:string"龙华"
“town”:string"观澜街道"
“town_id”:string"906263"
“town_code”:string""
“address”:string"库坑新围村皇帝印工业区 D 栋"
}
2:{
“original”:string"杭州市中河中路 258 号瑞丰国际商务大厦 5F"
“province”:string"浙江省"
“province_id”:string"334"
“province_code”:string"330000"
“province_shortname”:string"浙江"
“city”:string"杭州市"
“city_id”:string"336"
“city_code”:string"330100"
“city_shortname”:string"杭州"
“county”:string"上城区"
“county_id”:string"339"
“county_code”:string""
“county_shortname”:string"上城"
“town”:string"小营街道"
“town_id”:string"882646"
“town_code”:string""
“address”:string"中河中路 258 号瑞丰国际商务大厦 5F"
}
]
}
异常响应示例
JSON 示例
{
“code”:int400001
“msg”:string"业务参数有误,请检查"
“uid”:string"a6934adee62d8ba3430d4ac678dd5f46c7a79d6e"
“data”:{}
}
错误代码
错误码 描述
300101 快递单号创建失败
300102 获取快递单号失败
300103 不合法的请求参数
300103 图片格式错误
300104 签名格式不正确
300105 请求方式错误
300105 请求方式错误
300106 请求的的数据格式错误
300107 缺少必要参数
300108 用户 app_id 值不正确
300109 不存在的业务类型
300110 请求含有非法参数
300111 请求参数不能为空
300112 用户 app_key 值不正确
300115 业务参数有误,请检查
400001 业务参数有误
400002 超出批量解析最大数量限制
400003 输入字符太少
400004 请求方式错误
400005 请求数据格式错误
400006 缺少必要的参数
400007 类型不合法
400008 不支持的快递品牌 ****