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

Lizheng · 2022-03-24 14:48:35

API文档/地址库服务/智能解析

应用场景

1. 电商平台、电商ERP软件、物流应用软件等需要录入联系人信息，允许用户自由输入联系信息，无需分段按规格录入，提升录入效率和使用体验

2. 已有的联系人信息为纯文本，需要自动解析为姓名、电话、省市区、详细地址和备注

3. 用户输入的联系人信息中，省、市、区信息不全或有错误，需要自动纠正为完整、准确的行政区域信息

主要功能

1. 将包含收发件人信息的文本，识别为结构化的收发件人信息，返回姓名、电话号码、省、市、区、乡镇、详细地址、备注等分段信息，能够智能补全地址中缺失的行政区域

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

额外说明

技术咨询请加微信：kuaibao135

接口名称

cloud.address.resolve

公共参数

请求地址

环境名称	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格式响应数据

请求参数

名称	类型	是否必须	描述
multimode	bool	否	是否为批量模式，false为非批量，此时整个text参数认为是一条联系人信息；true为批量，此时根据text参数中的换行符区隔多条联系人信息。默认为true
text	string	是	包含地址、姓名、电话等信息的待解析文本，批量模式下多条记录用回车或换行符（\r\n）分割
resolveTown	int	否	是否从地址中解析乡镇、街道级别行政区域信息。0：不解析，1：地址中包含有乡镇、街道名称，则解析，否则不解析，2：不管地址中是否包含乡镇、街道名称，都尝试解析乡镇信息。默认值为0。若值为1或2，返回结果中会包含town_name，town_id, town_code字段，address字段中将不再包含乡镇级别行政区域信息

响应参数

名称	类型	是否必须	描述
original	string	是	输入的原始文本。响应体的data字段为一数组，每个数组元素为一条解析结果，本节描述的是每个元素的字段
mobile	string	是	手机号码
phone	string	是	固定电话
name	string	是	姓名
note	string	是	备注
province_name	string	是	省级名称
province_shortname	string	是	省级简称
province_id	string	是	省级快宝内部ID
province_code	string	是	省级行政区划代码
city_name	string	是	市级名称
city_shortname	string	是	市级简称
city_id	string	是	市级快宝内部ID
county_name	string	是	县级名称
county_shortname	string	是	县级简称
county_id	string	否	县级快宝内部ID
county_code	string	否	县级行政区划代码
town_name	string	否	乡镇、街道名称，仅在resolveTown为true时返回该值
town_id	string	否	乡镇、街道级别快宝内部ID，仅在resolveTown为true时返回该值
town_code	string	否	乡镇、街道级别行政区划代码
detail	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-Typeheaders.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.resolve";// 当前时间戳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", "{
    "text":"浙江省绍兴市诸暨市浣东街道西子公寓北区电话：13905857430  衣服  食物 ",
    "multimode":false
}");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"浙江省绍兴市诸暨市浣东街道西子公寓北区电话：13905857430 衣服食物 "

"phone":

string""

"mobile":

string"13905857430"

"name":

string"衣服食物"

"note":

string""

"province_id":

string"334"

"province_name":

string"浙江省"

"province_shortname":

string"浙江"

"province_code":

string"330000"

"city_id":

string"1304"

"city_name":

string"绍兴市"

"city_shortname":

string"绍兴"

"city_code":

string"330600"

"county_id":

string"1357"

"county_name":

string"诸暨市"

"county_shortname":

string"诸暨"

"county_code":

string"330681"

"detail":

string"西子公寓北区"

"town_id":

string"883331"

"town_name":

string"浣东街道"

"town_code":

string""

}

]

}

异常响应示例

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	不支持的快递品牌

网站开发技术

#1 2022-03-24 14:48:35