文档中心
一、国际地址解析接口 API调试工具

一、国际地址解析接口文档

该接口提供智能识别国际地址的功能,返回对应信息。

1.1 接口格式

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

1.2 请求地址

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

请求参数(header):

参数名类型默认值
Content-Typestringapplication/x-www-form-urlencoded

请求参数(body):

参数名是否必填类型说明
keystring授权码,请申请企业版获取
signstring32位大写,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号secret在企业管理后台查看
tstring时间戳如:1576123932000
paramparam由其他字段拼接

param数据结构:

参数名是否必填类型说明
codestring国家/地区二字码(不区分大小写),可参考国家/地区二字码列表附录
addressstring国际地址,如84 AlfordRd,GreatBarrington,MA01230,USA
languagestring语言码(不区分大小写),可参考支持的语言列表附录。该字段决定响应的解析结果以哪种语言进行展示

1.3 返回结果

字段类型说明备注
successboolean提交结果true提交成功,false失败
codestring返回编码
messagestring返回报文描述
timestring时间可忽略
dataObject

data数据结构

字段类型说明备注
taskIdstring任务ID
resultobject解析结果

result 的数据结构

字段类型说明备注
countrystring国家或地区
provincelist
citystring城市
districtstring区县
routestring路名/街道名
streetNumstring街道编号
postcodestring邮编

1.4 请求参数示例

key = xxx
sign = 4BBDE07660******0873642CFAE9A8DD
t = 1470304729724
param = {
    "code": "GB",
    "address": "221B Baker Street, London, NW1 6XE, United Kingdom",
    "language": "zh"
}

1.5 返回结果示例

成功示例:

{
    "code": 200,
    "data": {
        "taskId": "A4ACF3D322654F5FB7F34855D96C518B",
        "result": {
            "country": " 英国 ",
            "province": " 英格兰 ",
            "city": " 伦敦 ",
            "district": "",
            "route": " 贝克街 ",
            "streetNum": "221B",
            "postcode": "NW1 6XE"
        }
    },
    "message": "success",
    "time": 0,
    "success": true
}

失败示例1

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

失败示例2

{
   "code":-1,
   "data":null,
   "message":"解析失败,请稍后重试",
   "time":0,
   "success":false
}
 

1.6 返回信息代码含义:

信息代码信息内容描述原因及建议处理方式
-1解析失败/异常,请稍后重试快递100的服务器出现间歇或临时性异常,解析超时,也会报此错误
200提交成功提交成功
10002请求参数错误检查参数传参是否正确
30002验证签名失败检查加密方式,param +t+key+ secret的顺序进行MD5加密,加密后字符串转32位大写,不用加上“+”号
30004账号单量不足需要充值账号单量不足需要充值

1.7 国家/地区二字码列表附录

序号 国家(中文) 国家/地区二字码
1 阿联酋 AE
2 阿富汗 AF
3 安提瓜和巴布达 AG
4 安圭拉 AI
5 阿尔巴尼亚 AL
6 亚美尼亚 AM
7 安哥拉 AO
8 南极洲 AQ
9 阿根廷 AR
10 美属萨摩亚 AS
11 奥地利 AT
12 澳大利亚 AU
13 阿鲁巴 AW
14 阿塞拜疆 AZ
15 波黑 BA
16 巴巴多斯 BB
17 孟加拉国 BD
18 比利时 BE
19 布基纳法索 BF
20 保加利亚 BG
21 巴林 BH
22 布隆迪 BI
23 贝宁 BJ
24 圣巴泰勒米 BL
25 百慕大 BM
26 文莱 BN
27 玻利维亚 BO
28 荷属圣马丁 BQ
29 巴西 BR
30 巴哈马 BS
31 不丹 BT
32 布韦岛 BV
33 博茨瓦纳 BW
34 白俄罗斯 BY
35 伯利兹 BZ
36 加拿大 CA
37 科科斯(基林)群岛 CC
38 刚果(金) CD
39 中非共和国 CF
40 刚果(布) CG
41 瑞士 CH
42 科特迪瓦 CI
43 库克群岛 CK
44 智利 CL
45 喀麦隆 CM
46 中国 CN
47 哥伦比亚 CO
48 哥斯达黎加 CR
49 古巴 CU
50 佛得角 CV
51 库拉索 CW
52 圣诞岛 CX
53 塞浦路斯 CY
54 捷克 CZ
55 德国 DE
56 吉布提 DJ
57 丹麦 DK
58 多米尼克 DM
59 多米尼加 DO
60 阿尔及利亚 DZ
61 厄瓜多尔 EC
62 爱沙尼亚 EE
63 埃及 EG
64 西撒哈拉 EH
65 厄立特里亚 ER
66 西班牙 ES
67 埃塞俄比亚 ET
68 芬兰 FI
69 斐济 FJ
70 福克兰群岛 FK
71 密克罗尼西亚 FM
72 法罗群岛 FO
73 法国 FR
74 加蓬 GA
75 英国 GB
76 格林纳达 GD
77 格鲁吉亚 GE
78 法属圭亚那 GF
79 根西岛 GG
80 加纳 GH
81 直布罗陀 GI
82 格陵兰 GL
83 冈比亚 GM
84 几内亚 GN
85 瓜德罗普 GP
86 赤道几内亚 GQ
87 希腊 GR
88 危地马拉 GT
89 关岛 GU
90 几内亚比绍 GW
91 圭亚那 GY
92 中国香港 HK
93 赫德岛和麦克唐纳群岛 HM
94 洪都拉斯 HN
95 克罗地亚 HR
96 海地 HT
97 匈牙利 HU
98 印度尼西亚 ID
99 爱尔兰 IE
100 以色列 IL
101 马恩岛 IM
102 印度 IN
103 英属印度洋领地 IO
104 伊拉克 IQ
105 伊朗 IR
106 冰岛 IS
107 意大利 IT
108 泽西岛 JE
109 牙买加 JM
110 约旦 JO
111 日本 JP
112 肯尼亚 KE
113 吉尔吉斯斯坦 KG
114 柬埔寨 KH
115 基里巴斯 KI
116 科摩罗 KM
117 圣基茨和尼维斯 KN
118 朝鲜 KP
119 韩国 KR
120 科威特 KW
121 开曼群岛 KY
122 哈萨克斯坦 KZ
123 老挝 LA
124 黎巴嫩 LB
125 圣卢西亚 LC
126 列支敦士登 LI
127 斯里兰卡 LK
128 利比里亚 LR
129 莱索托 LS
130 立陶宛 LT
131 卢森堡 LU
132 拉脱维亚 LV
133 利比亚 LY
134 摩洛哥 MA
135 摩纳哥 MC
136 摩尔多瓦 MD
137 黑山 ME
138 马达加斯加 MG
139 马绍尔群岛 MH
140 北马其顿 MK
141 马里 ML
142 缅甸 MM
143 蒙古 MN
144 中国澳门 MO
145 北马里亚纳群岛 MP
146 马提尼克 MQ
147 毛里塔尼亚 MR
148 蒙特塞拉特岛 MS
149 马耳他 MT
150 毛里求斯 MU
151 马尔代夫 MV
152 马拉维 MW
153 墨西哥 MX
154 马来西亚 MY
155 莫桑比克 MZ
156 纳米比亚 NA
157 新喀里多尼亚 NC
158 尼日尔 NE
159 诺福克岛 NF
160 尼日利亚 NG
161 尼加拉瓜 NI
162 荷兰 NL
163 挪威 NO
164 尼泊尔 NP
165 纽埃 NU
166 瑙鲁 NR
167 新西兰 NZ
168 阿曼 OM
169 巴拿马 PA
170 秘鲁 PE
171 法属波利尼西亚 PF
172 巴布亚新几内亚 PG
173 菲律宾 PH
174 巴基斯坦 PK
175 波兰 PL
176 圣皮埃尔和密克隆 PM
177 皮特凯恩群岛 PN
178 波多黎各 PR
179 葡萄牙 PT
180 帕劳 PW
181 巴拉圭 PY
182 卡塔尔 QA
183 罗马尼亚 RO
184 塞尔维亚 RS
185 俄罗斯 RU
186 卢旺达 RW
187 沙特阿拉伯 SA
188 所罗门群岛 SB
189 塞舌尔 SC
190 苏丹 SD
191 瑞典 SE
192 新加坡 SG
193 圣赫勒拿岛 SH
194 斯洛文尼亚 SI
195 斯瓦尔巴群岛和扬马延岛 SJ
196 斯洛伐克 SK
197 塞拉利昂 SL
198 圣马力诺 SM
199 塞内加尔 SN
200 索马里 SO
201 苏里南 SR
202 南苏丹 SS
203 圣多美和普林西比 ST
204 萨尔瓦多 SV
205 叙利亚 SY
206 斯威士兰 SZ
207 特克斯和凯科斯群岛 TC
208 乍得 TD
209 多哥 TG
210 泰国 TH
211 塔吉克斯坦 TJ
212 托克劳 TK
213 东帝汶 TL
214 土库曼斯坦 TM
215 突尼斯 TN
216 汤加 TO
217 特立尼达和多巴哥 TT
218 图瓦卢 TV
219 中国台湾 TW
220 坦桑尼亚 TZ
221 乌克兰 UA
222 乌干达 UG
223 美国本土外小岛屿 UM
225 美国 US
226 乌拉圭 UY
227 乌兹别克斯坦 UZ
228 梵蒂冈 VA
229 圣文森特和格林纳丁斯 VC
230 委内瑞拉 VE
231 英属维尔京群岛 VG
232 美属维尔京群岛 VI
233 越南 VN
234 瓦努阿图 VU
235 瓦利斯和富图纳 WF
236 萨摩亚 WS
237 也门 YE
238 马约特 YT
239 南非 ZA
240 赞比亚 ZM
241 津巴布韦 ZW

1.8 支持的语言列表附录

序号 语言 语言码
1 阿拉伯语 ar
2 保加利亚语 bg
3 捷克语 cs
4 丹麦语 da
5 德语 de
6 希腊语 el
7 英语 en
8 西班牙语 es
9 芬兰语 fi
10 法语 fr
11 希伯来语 he
12 印地语 hi
13 克罗地亚语 hr
14 匈牙利语 hu
15 意大利语 it
16 日语 ja
17 韩语 ko
18 马来语 ms
19 荷兰语 nl
20 挪威语 no
21 波兰语 pl
22 葡萄牙语 pt
23 罗马尼亚语 ro
24 俄语 ru
25 塞尔维亚语 sr
26 瑞典语 sv
27 泰语 th
28 土耳其语 tr
29 乌克兰语 uk
30 越南语 vi
31 中文 zh