API
美国地址校验
更新时间： 2025-07-28 10:42:55 访问次数：2258

接口说明

该接口提供给第三方平台或是卖家自有系统。目前暂仅支持ontrac、usps、FedEx、UPS服务校验地址准确。其中暂仅FedEx服务支持校验地址类型。

注意：地址校验接口由于供应商环境限制，暂不支持沙箱环境测试，请直接调用生产环境

使用场景

  1. Ontrac 服务：卖家使用Ontrac区域派送供应商，可以通过该接口验证收货人地址是否正确，并获取建议地址用于修正。减少因地址错误产生地址修正附加费或包裹投递失败。
  2. USPS 服务：卖家使用USPS派送货物，可以通过该接口了解此地址是否被USPS识别，如可识别，USPS会提供该地址的规范输入地址；如不可识别，USPS会返回无法找到该地址，建议完善地址信息（注意：此接口仅做辅助下单参考，地址可识别不代表地址一定可以派送成功，地址不可识别不一定派送失败）
  3. FedEx 服务：卖家使用FedEx派送货物，可以通过该接口了解此地址是否被FedEx识别，如可识别，会提供该地址的规范输入地址和对应的地址类型；如不可识别，会返回无法找到该地址，建议完善地址信息（注意：此接口仅做辅助下单参考，地址可识别不代表地址一定可以派送成功，地址不可识别不一定派送失败）
  4. UPS服务：卖家使用UPS派送货物，暂仅提供对应的地址类型。注意UPS不会校验地址及返回建议地址信息。

接口名称

winit.tools.address.addressValid

请求说明

请求内容 说明
URL https://openapi.winit.com.cn/openapi/service
接口测试 https://sandboxopenapi.winit.com.cn/openapi/service
验证方法 Token,md5
格式 json
字符编码 UTF-8
http请求方式 http
请求数限制 默认每分钟100，100有需要可申请加大。

请求入参

名称 类型 必填 说明 示例
type string Y 校验类型
目前只支持ONTRAC、USPS、FedEx、UPS
country String Y 国家
ISO国家码或全称
state String Y 州
编码或全称
city String Y 城市
zipcode String Y 邮编
street String Y 街道
street2 String N 街道2

请求示例

Ontrac

  1. {
  2.     "action": "winit.tools.address.addressValid",
  3.     "app_key": "rebecca",
  4.     "data": {
  5.         "type":"ONTRAC",
  6.         "state":"California",
  7.         "city": "Hawthorne",
  8.         "country": "US",
  9.         "street": "13825 CRENSHAW",
  10.         "street2": " BLV",
  11.         "zipcode": "90250-7814"
  12.     },
  13.     "format": "json",
  14.     "language": "zh_CN",
  15.     "platform": "OWNERERP",
  16.     "sign": "00000000000000000000000000000000",
  17.     "sign_method": "md5",
  18.     "timestamp": "2015-06-16 00:19:26",
  19.     "version": "1.0"
  20. }

USPS

  1. {
  2.     "action": "winit.tools.address.addressValid",
  3.     "app_key": "rebecca",
  4.     "data": {
  5.         "type":"USPS",
  6.         "state":"California",
  7.         "city": "Hawthorne",
  8.         "street": "13825 CRENSHAW",
  9.         "street2": " BLV",
  10.         "zipcode": "90250-7814"
  11.     },
  12.     "format": "json",
  13.     "language": "zh_CN",
  14.     "platform": "OWNERERP",
  15.     "sign": "00000000000000000000000000000000",
  16.     "sign_method": "md5",
  17.     "timestamp": "2015-06-16 00:19:26",
  18.     "version": "1.0"
  19. }

FedEx

  1. {
  2.     "action": "winit.tools.address.addressValid",
  3.     "app_key": "rebecca",
  4.     "data": {
  5.         "type":"FedEx",
  6.         "state":"California",
  7.         "city": "Hawthorne",
  8.         "street": "13825 CRENSHAW",
  9.         "street2": " BLV",
  10.         "zipcode": "90250-7814"
  11.     },
  12.     "format": "json",
  13.     "language": "zh_CN",
  14.     "platform": "OWNERERP",
  15.     "sign": "00000000000000000000000000000000",
  16.     "sign_method": "md5",
  17.     "timestamp": "2015-06-16 00:19:26",
  18.     "version": "1.0"
  19. }

UPS

  1. {
  2.     "action": "winit.tools.address.addressValid",
  3.     "app_key": "rebecca",
  4.     "data": {
  5.         "type":"UPS",
  6.         "state":"California",
  7.         "city": "Hawthorne",
  8.         "street": "13825 CRENSHAW",
  9.         "street2": " BLV",
  10.         "zipcode": "90250-7814"
  11.     },
  12.     "format": "json",
  13.     "language": "zh_CN",
  14.     "platform": "OWNERERP",
  15.     "sign": "00000000000000000000000000000000",
  16.     "sign_method": "md5",
  17.     "timestamp": "2015-06-16 00:19:26",
  18.     "version": "1.0"
  19. }

返回出参

返回参数说明：正确的返回编码code：0及结果data，错误的返回错误码及错误信息msg。

名称 类型 必传 说明 示例
valid Boolean Y 校验结果
true：通过
false：不通过
注意：UPS不会校验地址准确，返回无效		 true
errorMessage String N 错误信息
classification String N 地址类型
暂仅FedEx、UPS会返回：
BUSINESS：商业
RESIDENTIAL：住宅
MIXED：混合（混合建议按住宅地址看，涉及住宅地址附加费）
UNKNOWN：不明确
suggestionList Object N 建议地址列表
USPS、FedEx 校验结果为true返回
Ontrac校验结果为false返回
UPS不会返回
– country String N 国家
Ontrac返回，USPS不返回
– state String Y 州
– city String Y 城市
– postalCode String Y 邮编
– streetName String N 街道
– streetName2 String N 街道2
Ontrac不返回
USPS、FedEx可能返回
– streetNumber String N 街道号
仅Ontrac返回
– streetNumberLow String N 最小街道号
仅Ontrac返回
– streetNumberHigh String N 最大街道号
仅Ontrac返回
– streetSide String N streetSide
仅Ontrac返回
– percentage String N 相似度
仅Ontrac返回

返回示例

异常返回：

  1. {
  2.     "code": "02010260004",
  3.     "msg": "检验失败:[state is null]",
  4.     "data": ""
  5. }

正常返回：

Ontrac校验通过

  1. {
  2.     "code": "0",
  3.     "msg": "操作成功",
  4.     "data": {
  5.         "valid": true,
  6.         "errorMessage": "",
  7.         "scrubbedAddress": null,
  8.         "suggestions": null,
  9.         "error": false
  10.     }
  11. }

Ontrac校验不通过

  1. {
  2.     "code": "0",
  3.     "msg": "操作成功",
  4.     "data": {
  5.         "valid": false,
  6.         "errorMessage": null,
  7.         "suggestions": [
  8.             {
  9.                 "streetNumberLow": "13801",
  10.                 "streetNumberHigh": "13899",
  11.                 "streetSide": "Odd",
  12.                 "streetNumber": "13825",
  13.                 "streetName": "CRENSHAW BLVD",
  14.                 "country": "US",
  15.                 "city": "HAWTHORNE",
  16.                 "postalCode": "90250",
  17.                 "percentage": 95,
  18.                 "state": "CA"
  19.             }
  20.         ],
  21.         "error": false
  22.     }
  23. }

USPS校验通过

  1. {
  2.     "code": "0",
  3.     "msg": "操作成功",
  4.     "data": {
  5.         "valid": true,
  6.         "errorMessage": null,
  7.         "suggestions": [
  8.             {
  9.                 "streetName": "CRENSHAW BLVD",
  10.                 "streetName2": "",
  11.                 "city": "HAWTHORNE",
  12.                 "postalCode": "90250",
  13.                 "state": "CA"
  14.             }
  15.         ],
  16.         "error": false
  17.     }
  18. }

USPS校验不通过

  1. {
  2.         "code": "0",
  3.         "msg": "操作成功",
  4.         "data": {
  5.                 "valid": false,
  6.                 "errorMessage": "Address Not Found.",
  7.                 "scrubbedAddress": null,
  8.                 "suggestions": null,
  9.                 "error": true
  10.         }
  11. }

FedEx校验通过

  1. {
  2.     "code": "0",
  3.     "msg": "操作成功",
  4.     "data": {
  5.         "valid": true,
  6.         "errorMessage": null,
  7.         "classification":"RESIDENTIAL",
  8.         "suggestions": [
  9.             {
  10.                 "streetName": "CRENSHAW BLVD",
  11.                 "streetName2": "",
  12.                 "city": "HAWTHORNE",
  13.                 "postalCode": "90250",
  14.                 "state": "CA"
  15.             }
  16.         ],
  17.         "error": false
  18.     }
  19. }

FedEx校验不通过

  1. {
  2.         "code": "0",
  3.         "msg": "操作成功",
  4.         "data": {
  5.                 "valid": false,
  6.                 "errorMessage": "GENERAL FAILURE {FAILURE_CAUSE}. Please update and try again.",
  7.                 "scrubbedAddress": null,
  8.                 "suggestions": null,
  9.                 "error": true
  10.         }
  11. }

UPS校验地址类型

  1. {
  2.     "code": "0",
  3.     "msg": "操作成功",
  4.     "data": {
  5.         "valid": true,
  6.         "errorMessage": null,
  7.         "classification":"RESIDENTIAL",//UNKOWN；COMMERCIAL；RESIDENTIAL
  8.         "scrubbedAddress": null,
  9.         "suggestions": null,
  10.         "error": false
  11.     }
  12. }
关键词