一、国际地址解析接口文档
该接口提供智能识别国际地址的功能,返回对应信息。
1.1 接口格式
提供统一格式的HTTP POST或GET调用接口,并返回统一格式JSON数据。
1.2 请求地址
https://api.kuaidi100.com/internationalAddress/resolution
请求参数(header):
| 参数名 | 类型 | 默认值 |
|---|---|---|
| Content-Type | string | application/x-www-form-urlencoded |
请求参数(body):
| 参数名 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| key | 是 | string | 授权码,请申请企业版获取 |
| sign | 是 | string | 32位大写,签名,用于验证身份,按MD5 (param +t+key+ secret)的顺序进行MD5加密,不需要加上“+”号secret在企业管理后台查看 |
| t | 是 | string | 时间戳如:1576123932000 |
| param | 是 | param | 由其他字段拼接 |
param数据结构:
| 参数名 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| code | 是 | string | 国家/地区二字码(不区分大小写),可参考国家/地区二字码列表附录 |
| address | 是 | string | 国际地址,如84 AlfordRd,GreatBarrington,MA01230,USA |
| language | 是 | string | 语言码(不区分大小写),可参考支持的语言列表附录。该字段决定响应的解析结果以哪种语言进行展示 |
1.3 返回结果
| 字段 | 类型 | 说明 | 备注 |
|---|---|---|---|
| success | boolean | 提交结果 | true提交成功,false失败 |
| code | string | 返回编码 | |
| message | string | 返回报文描述 | |
| time | string | 时间 | 可忽略 |
| data | Object |
data数据结构
| 字段 | 类型 | 说明 | 备注 |
|---|---|---|---|
| taskId | string | 任务ID | |
| result | object | 解析结果 |
result 的数据结构
| 字段 | 类型 | 说明 | 备注 |
|---|---|---|---|
| country | string | 国家或地区 | |
| province | list | 州 | |
| city | string | 城市 | |
| district | string | 区县 | |
| route | string | 路名/街道名 | |
| streetNum | string | 街道编号 | |
| postcode | string | 邮编 |
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 |