阿里云地址标准化服务完全对接指南：从开通到生产级API调用
一、什么是阿里云地址标准化
地址标准化（Address Purification）是阿里云依托海量地址语料库与强大的自然语言处理算法实力所沉淀出的高性能、高准确率的标准地址算法服务。该服务能够解决一地多名、地址解析、地址真伪辨别等多种实际问题，为企业、政府机关以及开发者提供地址数据清洗与标准化能力。
从技术架构上看，地址标准化是一站式闭环地址数据处理和服务平台。它针对各行业业务系统所登记的地址数据，进行纠错、补全、归一、结构化、标签化等NLP处理清洗，实现地址库的标准化，并向上提供地址智能填写、地址搜索与联想、地址正逆编码、地址围栏等高级地址服务。
地址标准化接口服务包含基础服务和高级服务两大类。其中高级服务涵盖地址文本清洗、地址智能填写、智能地址应用、地址空间化、地点特征分析、语音对话场景六个场景，共计二十余个接口。
二、核心能力与功能接口
地址标准化当前支持的核心功能包括：地址结构化、物流面单信息提取、门址标准化、地址归一、地址补齐、行政区划识别、邮编识别。以下对主要接口逐一说明：
- 地址结构化（StructureAddress）：对地址片段进行结构化解析，识别省、市、区、街道、路名、门牌号等地址要素。
- 地址纠错（CorrectAddress）：对用户输入的地址进行错误检测与修正，包括行政区划名称纠错、路名路号纠错等。
- 地址补全：对缺省地址信息进行补全，自动填充缺失的行政区划或街道信息。
- 门址标准化：对用户原始地址进行补全，同时对行政区划及路名、路号等错误信息进行修正，输出标准地名信息。
- 地址归一（OneAddress）：将不同表述方式的同一地址归一化为标准表达，解决“北京市朝阳区建国路88号”与“北京朝阳建国路88号”这类同址异名问题。
- 行政区划识别：从地址文本中提取省、市、区、县等行政区划信息。
- 邮编识别：根据地址信息识别对应的邮政编码。
- 高精度经纬度查询（HpGeocode）：将地址解析为经纬度坐标，支持楼栋级别精度。
在版本升级方面，地址标准化已新增多地址一致性判断、地址异常诊断等核心能力，模型效果持续提升，同时增加了定制干预管理模块，支持用户通过线上自定义实现模型badcase的自助修复。
三、对接前的准备工作
在使用地址标准化服务之前，需要完成以下几个准备步骤。
3.1 开通阿里云账号与服务
首先需要注册并登录阿里云账号。从阿里云官网首页导航栏选择“产品分类”→“人工智能与机器学习”→“自然语言处理”→“地址标准化”，进入产品详情页。也可以直接在首页搜索栏搜索“地址标准化”进入产品页面。在产品页面点击开通服务，根据指引完成服务的开通操作。
需要先登录阿里云控制台，点击：阿里云控制台
3.2 创建项目
开通服务后，需要创建项目来管理API调用。操作路径为：打开地址标准化控制台，在左侧菜单选择“我的项目”，然后点击“创建项目”按钮。在弹出的对话框中输入项目名称和描述信息，点击确认完成创建。项目创建后，系统会为每个项目生成唯一的AppKey，后续调用API时需要携带此AppKey进行身份识别。
3.3 RAM权限配置
为了保证账号安全，推荐使用RAM子账号进行API调用，而非直接使用主账号的AccessKey。RAM（访问控制）是阿里云提供的身份管理与访问控制服务，可以精细化管理用户对云资源的访问权限。
RAM用户默认没有任何权限，需要由阿里云账号管理员为其授权后才能访问地址标准化服务。具体操作流程如下：
- 登录RAM控制台，创建一个RAM用户。
- 为RAM用户授予地址标准化的相关权限策略。系统提供了两种预设策略：AliyunAddrpFullAccess（管理地址标准化服务的权限）和AliyunAddrpReadOnlyAccess（只读访问地址标准化服务的权限）。
- 如果系统策略不满足需求，可以创建自定义权限策略，采用脚本编辑模式配置精细化的Action和Resource授权。
- 在“身份管理-用户”中为RAM用户添加授权，完成后RAM用户即可通过AccessKey调用地址标准化API。
推荐的做法是：将人员用户和程序用户分离，为不同的应用程序创建独立的RAM用户并授予最小权限。
四、API调用方式详解
地址标准化的API采用RPC风格，支持通过发送HTTP GET或POST请求进行调用。下面详细介绍API的请求结构与调用方法。
4.1 请求结构
API请求的基本结构如下：
https://Endpoint/?Action=xx&Parameters其中各组成部分的含义为：
- Endpoint：服务接入地址，固定为
address-purification.cn-hangzhou.aliyuncs.com。 - Action：要执行的操作名称，例如调用地址结构化接口时取值为
StructureAddress。 - Version：API版本号，地址标准化的API版本是
2019-11-18。 - Parameters：请求参数，包含公共请求参数和API自定义参数，参数之间用“&”分隔。
4.2 公共参数
每个API请求都需要携带以下公共参数：
- AccessKeyId：访问密钥ID，用于标识调用者身份。
- Signature：请求签名，用于验证请求的合法性。
- SignatureMethod：签名算法，固定为
HMAC-SHA1。 - SignatureVersion：签名版本，固定为
1.0。 - SignatureNonce：唯一随机数，用于防止请求重放攻击。
- Timestamp：请求的时间戳，格式为
YYYY-MM-DDThh:mm:ssZ。 - Format：返回结果的格式，支持JSON和XML。
4.3 签名机制
签名计算是API调用的核心安全环节。签名流程如下：
- 构造规范化的请求字符串（Canonicalized Query String）：将所有请求参数按参数名称的字典序排列，使用
=连接参数名与参数值，参数之间用&连接。 - 构造待签名字符串（StringToSign）：格式为
HTTP方法 & 编码后的URI & 编码后的规范化请求字符串。 - 使用AccessKey Secret对StringToSign进行HMAC-SHA1加密，将结果进行Base64编码得到签名。
- 将签名添加到请求参数中，参数名为
Signature。 - 多地址一致性判断：判断多个地址描述是否指向同一地理位置。
- 地址异常诊断：检测地址中存在的异常信息。
- 地址POI类型识别：识别地址对应的POI（兴趣点）类型。
- 语音场景优化：针对语音场景提供专门优化，包括语音地址识别和对话上下文地址推理功能，可应用于语音导航、智能客服等场景。
- 在正式上线前，充分利用各接口500次的免费额度进行功能验证和压力测试。
- 根据实际业务调用量选择合适的计费方式，避免按量计费带来的成本波动。
- 关注控制台的数据监控，及时发现异常调用并采取措施。
- 如有私有化部署需求，可在官网点击“私有化版本咨询”，由售前人员提供定制方案。
实际开发中，阿里云SDK已自动封装了签名逻辑，开发者无需手动计算签名。
五、SDK接入与代码示例
阿里云为地址标准化提供了多语言SDK，包括Java、Python、Go、.Net、C++、PHP等。开发者可以在 https://open.aliyun.com/sdk 页面搜索“地址标准化”下载对应语言的SDK安装包。地址标准化SDK封装了2019-11-18版本API，以访问密钥识别调用者身份，提供自动签名等功能。使用地址标准化功能需要同时安装地址标准化SDK和阿里云核心库。
5.1 Python SDK 示例
首先安装Python SDK：
pip install aliyunsdkcore aliyunsdkaddress_purification以下是一个调用地址结构化接口的完整Python示例：
from aliyunsdkcore.client import AcsClient
from aliyunsdkaddress_purification.request.v20191118 import StructureAddressRequest
# 初始化客户端
client = AcsClient(
'您的AccessKeyId',
'您的AccessKeySecret',
'cn-hangzhou'
)
# 构造请求对象
request = StructureAddressRequest.StructureAddressRequest()
request.set_accept_format('json')
# 设置请求参数
request.set_AppKey('您的项目AppKey')
request.set_ServiceCode('addrp')
request.set_Text('杭州市余杭区五常街道文一西路969号阿里巴巴西溪园区')
request.set_DefaultProvince('浙江省')
request.set_DefaultCity('杭州市')
request.set_DefaultDistrict('余杭区')
# 发起请求并获取响应
try:
response = client.do_action_with_exception(request)
print(response.decode('utf-8'))
except Exception as e:
print(f'调用失败: {e}')以下是调用高精度经纬度查询接口（楼栋级别）的示例：
from aliyunsdkcore.client import AcsClient
from aliyunsdkaddress_purification.request.v20191118 import HpGeocodeRequest
client = AcsClient('您的AccessKeyId', '您的AccessKeySecret', 'cn-hangzhou')
request = HpGeocodeRequest.HpGeocodeRequest()
request.set_accept_format('json')
request.set_Text('杭州市阿里巴巴西溪园区')
request.set_DefaultProvince('浙江省')
request.set_DefaultCity('杭州市')
request.set_DefaultDistrict('余杭区')
response = client.do_action_with_exception(request)
print(response.decode('utf-8'))5.2 Java SDK 示例
使用Java SDK需要引入以下Maven依赖：
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aliyun-java-sdk-core</artifactId>
<version>4.6.3</version>
</dependency>
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aliyun-java-sdk-address-purification</artifactId>
<version>1.0.0</version>
</dependency>以下是Java调用地址纠错接口的示例：
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.address_purification.model.v20191118.CorrectAddressRequest;
import com.aliyuncs.address_purification.model.v20191118.CorrectAddressResponse;
import com.alibaba.fastjson.JSONObject;
public class AddressCorrectionDemo {
public static void main(String[] args) {
// 创建客户端
DefaultProfile profile = DefaultProfile.getProfile(
"cn-hangzhou",
"您的AccessKeyId",
"您的AccessKeySecret"
);
IAcsClient client = new DefaultAcsClient(profile);
// 构造请求
CorrectAddressRequest request = new CorrectAddressRequest();
request.setAppKey("您的项目AppKey");
request.setServiceCode("addrp");
request.setText("北京朝阳区建国路88号");
request.setDefaultProvince("北京市");
request.setDefaultCity("北京市");
try {
CorrectAddressResponse response = client.getAcsResponse(request);
System.out.println(JSONObject.toJSONString(response));
} catch (Exception e) {
e.printStackTrace();
}
}
}5.3 直接调用HTTP API示例
如果不使用SDK，也可以直接发送HTTP请求调用API：
https://address-purification.cn-hangzhou.aliyuncs.com/
?Action=StructureAddress
&Format=JSON
&Version=2019-11-18
&AccessKeyId=您的AccessKeyId
&Signature=计算出的签名值
&SignatureMethod=HMAC-SHA1
&SignatureNonce=唯一随机数
&SignatureVersion=1.0
&Timestamp=2026-07-12T10:00:00Z
&AppKey=您的项目AppKey
&ServiceCode=addrp
&Text=杭州市余杭区文一西路969号六、控制台测试与监控
6.1 API测试和体验
在正式编写代码之前，可以先在控制台进行API测试，验证接口功能和返回结果。操作路径为：打开地址标准化控制台，在左侧菜单选择“API测试和体验”。在项目选择的下拉菜单中选择对应的项目，然后选择需要测试的API，在测试地址的文本框中输入地址，点击“开始测试”即可获得结果。
6.2 数据监控与统计
控制台提供了完善的数据监控功能。在左侧菜单中选择“数据监控”，可以查询不同项目在不同时间段内的服务调用量和QPS统计，并以折线图的形式直观展现。在图表上方可以选择不同的时间维度进行查看，也可以自定义时间间隔。数据监控会存在小时级别的延迟，建议定期查看以掌握服务使用情况。
6.3 定制干预管理
当模型对某些特定地址的处理结果不满足业务需求时，可以通过定制干预管理进行修正。在控制台左侧菜单选择“定制管理”，点击“创建实例”可以新建一条实例干预修正规则。通过下拉选择项目并配置干预规则，即可实现模型badcase的自助修复。
七、地址归一化与高级能力
地址归一化是地址标准化的一项核心高级能力。在电商、物流、O2O等业务场景中，用户提交的收货地址往往存在大量非标准化表达。例如，“北京市朝阳区建国路88号”与“北京朝阳建国路88号”、“北京市朝阳区建外街道建国路88号”虽然指向同一地点，但在系统中被视为不同地址，导致订单合并困难、配送路径规划低效、用户画像不准等问题。地址归一化接口能够将这些不同表述归一为标准地址，有效解决上述问题。
此外，地址标准化还提供了以下高级能力：
八、计费方式与成本优化
8.1 计费模式
地址标准化采用灵活的计费方式，主要包括按量后付费和资源包预付费两种模式。
按量后付费：根据实际API调用次数计费，各接口有独立的单价。基础服务中，地址抽取为2.8元/千次，地址结构化为6元/千次。每个API接口默认提供500次的免费调用额度。免费额度用尽后继续调用会产生后付费账单。默认QPS为10，如当前QPS不满足业务需求，可以付费调整。
资源包预付费：适合调用量较大的场景。中小企业调用量起伏较大且每月调用总量小于2500万次时，推荐购买流量资源包。资源包不限制API接口，同服务类型下各API接口共用次数，有效期为开通后起开始计算的十二个月。中大企业若固定使用一个或几个API接口、调用量较大且每月调用总量大于2500万次，建议考虑包月订阅以降低成本。
8.2 成本优化建议
九、常见问题与解决方案
问题1：调用接口时一直报错，是什么原因？
答：接口报错通常由以下几个原因引起：未开通服务或服务已欠费停服；AccessKey或AppKey配置错误；RAM用户未获得相应权限；请求参数格式不符合要求。建议先检查控制台的服务状态，确认账号未欠费，然后核对AccessKey和AppKey是否正确，最后检查RAM权限配置。如果问题仍然存在，可以根据错误码定位具体原因。
问题2：没有创建项目是否可以调用接口？
答：不可以。测试和调用功能接口前，必须在控制台创建项目。每个项目有独立的AppKey，用于API调用时的身份识别。
问题3：地址补全功能识别结果不准怎么办？
答：如果地址补全功能识别不准确，可以尝试使用门址标准化功能。门址标准化 = 地址纠错 + 地址补全，能同时对地址进行纠错和补全。如果补全结果中存在重复元素，可以在做地址文本拼接时筛去重复部分。此外，还可以通过定制干预管理对特定badcase进行修正。
问题4：地址标准化仅支持国内地址吗？
答：地址标准化主要面向国内地址提供纠错、补全、归一化等功能。如涉及港澳台或海外特殊行政区划，建议在选型前进行充分测试。
问题5：各功能接口的免费额度是多少？
答：地址标准化基础服务接口和高级服务接口分别有500次的免费额度。各接口共享对应服务类型的免费额度，用尽后按后付费价格计费。
问题6：如何获取技术支持？
答：如有产品使用问题，可以加入官方钉钉群：35111738。如需私有化部署咨询，可在官网点击“私有化版本咨询”联系售前人员。
