USPS 地址验证 API 使用指南
USPS 地址验证 API 使用指南
USPS Address Validation API 是美国邮政局官方提供的地址验证服务，可以帮助开发者验证地址的真实性并获取标准化格式。本文将介绍该 API 的功能、接入方法和使用示例。
API 概述
USPS Address Validation API（原名 Address Standardization & Verification API）提供以下功能：
接入准备
注册 USPS Web Tools 账号
API 端点
USPS 提供了两个环境：
API 调用方法
请求格式
USPS API 使用 XML 格式进行请求和响应。以下是一个验证地址的请求示例：
```xml
<AddressValidateRequest USERID="YOUR_USERID">
<Revision>1</Revision>
<Address ID="0">
<Address1>1234 Main St</Address1>
<Address2>Apt 5B</Address2>
<City>Los Angeles</City>
<State>CA</State>
<Zip5>90001</Zip5>
<Zip4></Zip4>
</Address>
</AddressValidateRequest>
```
响应格式
```xml
<AddressValidateResponse>
<Address ID="0">
<Address2>1234 MAIN ST</Address2>
<Address1>APT 5B</Address1>
<City>LOS ANGELES</City>
<State>CA</State>
<Zip5>90001</Zip5>
<Zip4>1234</Zip4>
</Address>
</AddressValidateResponse>
```
JavaScript 调用示例
```javascript
async function verifyAddress(address) {
const xml = '<AddressValidateRequest USERID="' + USERID + '">' +
'<Revision>1</Revision>' +
'<Address ID="0">' +
'<Address1>' + address.street + '</Address1>' +
'<Address2>' + address.apt + '</Address2>' +
'<City>' + address.city + '</City>' +
'<State>' + address.state + '</State>' +
'<Zip5>' + address.zip5 + '</Zip5>' +
'<Zip4></Zip4>' +
'</Address></AddressValidateRequest>';
const url = 'https://secure.shippingapis.com/ShippingAPI.dll?API=Verify&XML=' + encodeURIComponent(xml);
const response = await fetch(url);
const text = await response.text();
return text;
}
```
字段说明
USPS API 中的字段与标准地址格式有对应关系：
| API 字段 | 说明 | 对应地址字段 |
|---|---|---|
| Address1 | 公寓/套房号 | Address Line 2 |
| Address2 | 街道地址 | Address Line 1 |
| City | 城市 | City |
| State | 州缩写 | State |
| Zip5 | 5 位邮编 | ZIP Code |
| Zip4 | 4 位扩展 | ZIP+4 |
> 注意：USPS API 中 Address1 是公寓号，Address2 是街道地址，这与常见的表单设计相反。
错误处理
API 响应中可能包含错误信息：
```xml
<Address ID="0">
<Error>
<Number>-2147219400</Number>
<Description>Address Not Found.</Description>
</Error>
</Address>
```
常见错误：
| 错误描述 | 说明 |
|---|---|
| Address Not Found | 地址不存在 |
| Invalid City | 城市名无效 |
| Invalid State | 州代码无效 |
| Multiple addresses were found | 存在多个匹配地址 |
使用建议
| 建议 | 说明 |
|---|---|
| 缓存结果 | 相同地址的验证结果可缓存，减少 API 调用 |
| 批量验证 | USPS API 支持一次请求验证多个地址（最多 5 个） |
| 降级处理 | API 不可用时应降级为本地格式校验 |
| 速率控制 | 遵守 USPS 的速率限制，避免被封禁 |
替代方案
如果 USPS API 无法满足需求，可以考虑以下第三方服务：
小结
USPS Address Validation API 是验证美国地址的权威工具，适合需要高精度地址验证的场景。在接入时需要注意其 XML 格式和特殊的字段映射关系。对于更高并发或更丰富功能的需求，可以考虑第三方地址验证服务。