阿里云地址标准化API对接使用完全指南

apphuang2026年07月12日 16:22:391

一、地址标准化产品概述

地址标准化（Address Purification）是阿里云依托海量地址语料库与强大的自然语言处理算法所打造的一站式闭环地址数据处理和服务平台。该产品能够有效解决地址数据中普遍存在的一地多名、地址解析困难、地址真伪辨别等问题，为企业、政府机关以及开发者提供专业级的地址数据清洗与标准化能力。

地址标准化接口服务包含基础服务和高级服务两大类别。其中高级服务涵盖了地址文本清洗、地址智能填写、智能地址应用、地址空间化、地点特征分析、语音对话场景六个场景，共计二十余个功能接口。全程都可以使用封装好的API直接调用，用户无需自行标注地址数据，无需进行模型训练，也无需具备算法基础。

需要先登录阿里云控制台，点击：阿里云控制台

二、开通服务与前期准备

2.1 开通地址标准化服务

使用地址标准化服务的第一步是开通服务。具体操作如下：从阿里云官网首页导航栏选择“产品分类”->“人工智能与机器学习”->“自然语言处理”->“地址标准化”，进入产品详情页。您也可以在首页搜索栏直接搜索“地址标准化”快速定位产品页面。进入产品页后，根据页面提示完成服务的开通操作。

对于初次使用的用户，阿里云提供了试用额度。地址标准化基础服务接口和高级服务接口分别享有500次的免费调用额度。试用额度用尽后，继续调用将产生后付费账单。如需优惠使用，可以前往“服务管理与开通”页面购买对应的资源包或包月服务。

2.2 创建项目

开通服务后，需要在地址标准化控制台中创建项目。项目是管理API调用和组织地址数据处理任务的基本单元。操作步骤如下：

登录地址标准化控制台，在左侧菜单栏选择“我的项目”。
点击页面中的“创建项目”按钮。
在弹出的对话框中输入项目名称和描述信息，点击“确认”完成创建。

值得注意的是，在调用任何功能接口之前，必须先创建项目。项目创建完成后，系统会为该项目生成一个唯一的AppKey，后续调用API时需要在请求中携带该AppKey以标识调用来源。

2.3 获取AccessKey

调用阿里云OpenAPI需要持有有效的访问密钥（AccessKey），用于身份认证和请求签名。AccessKey由AccessKey ID和AccessKey Secret两部分组成。您可以通过以下方式获取：登录阿里云控制台，点击右上角头像进入“AccessKey管理”页面，按照指引创建新的AccessKey。请妥善保管AccessKey Secret，切勿泄露给他人或在代码中硬编码明文密钥。

2.4 RAM子账号权限配置（可选）

出于安全考虑，建议使用RAM子账号而非主账号调用API。使用RAM账号调用地址标准化API前，需要由阿里云主账号在RAM访问控制中创建自定义权限策略并对RAM用户进行授权。具体的API鉴权规则和操作流程如下：在RAM访问控制的“权限策略”中新建权限策略，使用脚本编辑模式编写授权策略，然后将该策略授权给指定的RAM用户。

三、API调用方式与请求结构

3.1 调用方式概述

地址标准化的API采用RPC风格，支持通过发送HTTP GET请求来调用API。请求结构如下：

https://Endpoint/?Action=xx&Parameters

其中各组成部分的含义为：

Endpoint：服务接入地址，固定为 address-purification.cn-hangzhou.aliyuncs.com。
Action：要执行的操作名称，例如调用ClassifyPOI接口进行POI分类。
Version：API版本号，地址标准化的API版本为 2019-11-18。
Parameters：请求参数，包含公共请求参数和API自定义参数，各参数之间用“&”分隔。

3.2 公共参数

每次API调用都需要携带一组公共参数，用于身份验证和请求管理。主要包括：

AccessKeyId：您的AccessKey ID。
Signature：请求签名，由AccessKey Secret对请求参数进行加密计算得出。
SignatureMethod：签名方法，固定为 HMAC-SHA1。
SignatureNonce：唯一随机数，用于防止请求重放攻击。
SignatureVersion：签名版本号。
Timestamp：请求的时间戳，格式为ISO 8601。
Format：返回数据格式，支持XML和JSON两种，默认为XML。

3.3 返回数据格式

API返回结果采用统一格式。无论调用成功与否，系统都会返回一个唯一识别码RequestId。返回的数据格式可以在请求时通过Format参数指定为XML或JSON。对于JSON格式的返回结果，通常会包含请求ID、业务数据以及状态信息等字段。

四、核心API接口详解

4.1 地址结构化（AddressStructure）

地址结构化接口能够将非结构化的地址文本拆解为省、市、区、街道、路名、门牌号等结构化组件。该接口适用于需要从自由文本中提取地址要素的场景。请求参数主要包括待处理的地址文本Text，以及可选的默认省份DefaultProvince、默认城市DefaultCity、默认行政区DefaultDistrict。返回结果中会包含结构化的地址信息和处理耗时等数据。

4.2 地址补全（CompleteAddress）

地址补全接口能够对输入地址中缺失的行政区划信息以及路名路号进行智能补全。例如输入“文一西路969号”，系统会自动补全为“浙江省杭州市余杭区五常街道文一西路969号”。请求参数同样包含Text、DefaultProvince、DefaultCity和DefaultDistrict。返回的complete字段即为补全后的完整地址。

4.3 地址纠错（AddressCorrect）

地址纠错接口用于识别和修正地址文本中的错误信息，包括错别字、行政区划错误、路名路号错误等。该接口能够将不规范甚至错误的地址修正为正确的标准地址，是数据清洗环节的核心工具之一。

4.4 地址异常检测（AddressAssessment）

地址异常检测接口用于判断输入地址是否为问题地址，并评估地址数据的质量。返回结果会标明地址是否存在异常以及异常的具体类型，帮助用户识别数据中的脏数据。

4.5 门址标准化（StandardizationAddress）

门址标准化是对用户原始地址进行标准化处理的服务，包括对缺省地址信息进行补全，同时对行政区划（省/市/区/街道）及路名、路号等错误信息进行修正，最终输出规范标准的地名信息。该接口综合了地址纠错和地址补全的能力，是地址标准化的综合性接口。

4.6 地址相似度判断（GetAddressSimilarity）

地址相似度判断接口用于比较两个地址文本的相似程度。该接口适用于地址去重、地址匹配等场景，返回的相似度分值可以帮助判断两条地址记录是否指向同一地理位置。

4.7 POI分类（ClassifyPOI）

POI分类接口能够对地址文本中的兴趣点（Point of Interest）进行分类。例如识别地址中的场所类型是餐饮、购物、住宅还是公共服务设施等。该接口对于地址标签化和场景化分析具有重要价值。

4.8 高精度经纬度查询（HpGeocode）

高精度经纬度查询接口能够将地址文本转换为精确的经纬度坐标，精度可达楼栋级别。请求参数包括待查询的地址文本Text，以及可选的默认省份、默认城市、默认行政区。返回结果中包含高精度的经纬度信息。

五、多语言SDK集成指南

地址标准化SDK封装了2019-11-18版本的API，以AccessKey识别调用者身份，并提供自动签名等功能。使用地址标准化功能需要同时安装地址标准化SDK和阿里云核心库。阿里云官方SDK支持Java、Python、Go、.Net、C++、PHP等多种编程语言。SDK安装包可以在 open.aliyun.com/sdk 页面搜索“地址标准化”下载。

5.1 Python SDK

使用Python SDK调用地址标准化API，首先需要通过pip安装必要的依赖包：

pip install aliyunsdkcore aliyunsdkaddress_purification

安装完成后，可以参考以下示例代码调用高精度经纬度查询接口：

from aliyunsdkcore.client import AcsClient
from aliyunsdkaddress_purification.request.v20191118.HpGeocodeRequest import HpGeocodeRequest

# 初始化客户端
client = AcsClient(
    '<您的AccessKeyId>',
    '<您的AccessKeySecret>',
    'cn-hangzhou'
)

# 构造请求对象
request = HpGeocodeRequest()
request.set_accept_format('json')

# 设置请求参数
request.set_Text('杭州市阿里巴巴西溪园区A区')
request.set_DefaultProvince('浙江省')
request.set_DefaultCity('杭州市')
request.set_DefaultDistrict('余杭区')

# 发起请求并获取响应
response = client.do_action_with_exception(request)
print(response)

上述代码中，需要将AccessKeyId和AccessKeySecret替换为您实际的密钥值。Region参数填写为服务所在地域，地址标准化服务目前接入地址为cn-hangzhou。

5.2 Java SDK

使用Java SDK需要在项目的pom.xml文件中添加以下依赖：

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>4.5.0</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-address-purification</artifactId>
    <version>1.0.0</version>
</dependency>

Java SDK的调用示例代码如下：

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.address_purification.model.v20191118.CompleteAddressRequest;
import com.aliyuncs.address_purification.model.v20191118.CompleteAddressResponse;

public class AddressPurificationDemo {
    public static void main(String[] args) {
        // 创建Client实例
        DefaultProfile profile = DefaultProfile.getProfile(
            "cn-hangzhou",
            "<您的AccessKeyId>",
            "<您的AccessKeySecret>"
        );
        IAcsClient client = new DefaultAcsClient(profile);
        
        // 构造请求
        CompleteAddressRequest request = new CompleteAddressRequest();
        request.setAppKey("<您的项目AppKey>");
        request.setServiceCode("addrp");
        request.setText("文一西路969号");
        request.setDefaultProvince("浙江省");
        request.setDefaultCity("杭州市");
        request.setDefaultDistrict("余杭区");
        
        try {
            CompleteAddressResponse response = client.getAcsResponse(request);
            System.out.println(response.getData());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

5.3 Go SDK

Go SDK的使用方式与其他语言类似，同样需要先安装SDK包，然后初始化客户端并构造请求对象。阿里云官方提供了完整的Go SDK支持，可以在open.aliyun.com页面获取。

六、控制台测试与调试

地址标准化控制台提供了便捷的API测试和体验功能，无需编写代码即可验证接口效果。操作步骤如下：

登录地址标准化控制台，在左侧菜单选择“API测试和体验”。
在项目选择的下拉菜单中选择对应的项目。
选择需要测试的API接口。
在测试地址的文本框中输入待测试的地址，点击“开始测试”即可获得结果。

控制台测试是快速验证接口功能和调试参数的有效手段，尤其适合在正式集成前确认接口的输入输出格式。

七、数据监控与统计

地址标准化控制台提供了完善的数据监控功能。在控制台左侧菜单点击“数据监控”，可以查询不同项目在不同时间段内的服务调用量和QPS统计，并以折线图的形式直观展现。在图表上方可以选择不同的时间维度进行查看，也支持自定义时间间隔。数据监控功能对于了解API使用情况、发现异常调用以及进行容量规划都具有重要意义。

八、安全与权限管理

8.1 RAM鉴权配置

地址标准化服务支持通过RAM（资源访问管理）进行细粒度的权限控制。RAM鉴权的核心操作流程包括：在RAM访问控制中创建自定义权限策略，使用脚本编辑模式编写权限规则，然后将策略授权给指定的RAM用户。通过RAM授权，可以实现最小权限原则，有效降低AccessKey泄露带来的安全风险。

8.2 AccessKey安全最佳实践

AccessKey是调用API的核心凭证，其安全性至关重要。建议遵循以下最佳实践：使用RAM子账号的AccessKey而非主账号的AccessKey；定期轮换AccessKey；不在代码中硬编码AccessKey Secret，而是使用环境变量或配置中心管理；为不同的应用或服务分配不同的AccessKey以便于追踪和隔离风险。

九、计费方式与成本优化

9.1 计费模式

地址标准化服务采用后付费（按量计费）模式，同时提供资源包和包月服务供用户选择。以基础服务为例，地址抽取接口的后付费价格为2.8元/千次。各接口均享有免费的调用额度，基础服务和高级服务各500次。

9.2 成本优化建议

对于调用量较大的企业用户，建议购买包月服务或资源包以降低成本。包月服务以单个API接口售卖，适用于固定使用一个或几个API接口、每月调用总量大于2500万次的中大企业场景。同时，建议在控制台中开启数据监控，及时了解调用量变化，避免超额调用产生意外账单。

十、常见问题与排查思路

10.1 接口调用报错

地址标准化接口调用报错通常与权限配置、参数错误或服务开通状态有关。建议首先检查服务是否已开通、项目是否已创建、AppKey是否正确。其次确认AccessKey是否有调用该接口的权限。最后检查请求参数是否符合接口要求，特别是必填参数是否完整、参数格式是否正确。

10.2 地址识别结果不准确

如果地址补全或标准化结果不准确，可能是因为输入地址本身存在较多错误信息。可以尝试使用门址标准化接口，该接口综合了地址纠错和地址补全的能力。另外，在请求中正确设置默认省份、默认城市和默认行政区参数，有助于提高识别准确率。

10.3 数据不留存

地址标准化服务处理的数据不会在服务端留存。如果需要保留处理记录，建议在调用API后自行在本地记录日志。

十一、总结

阿里云地址标准化服务提供了从地址解析、纠错、补全到结构化、编码、分类的一站式地址数据处理能力。通过本文的介绍，您应该已经掌握了从开通服务、创建项目、获取密钥，到API调用、SDK集成、控制台调试、监控运维的全流程操作。无论是物流行业的地址智能填写、电商平台的收货地址标准化、还是地理位置服务的坐标转换，地址标准化都能够为您的业务提供专业、高效、准确的技术支撑。

常见问题解答

问1：地址标准化服务是否支持批量地址处理？
答：地址标准化API目前为单条地址处理模式，不支持在单次请求中批量处理多条地址。批量处理的通用做法是：获取需要标准化的地址列表，循环调用单条地址标准化的API对每个地址进行解析，最后汇总所有标准化完成的地址。

问2：地址标准化服务是否仅支持国内地址？
答：地址标准化服务主要依托阿里云海量的国内地址语料库构建，目前主要支持国内地址的标准化处理。对于海外地址的支持能力有限，建议根据具体业务需求进行验证。

问3：地址标准化接口调用有免费额度吗？
答：有的。地址标准化基础服务接口和高级服务接口分别享有500次的免费调用额度。免费额度用尽后，继续调用将按后付费价格计费。

问4：调用地址标准化API必须创建项目吗？
答：是的。测试和调用任何功能接口前，必须在地址标准化控制台中创建项目。项目创建完成后会生成AppKey，调用API时需要在请求中携带该AppKey。

问5：地址标准化服务的数据会留存吗？
答：不会。地址标准化服务处理的数据不会在服务端留存。如果需要保留处理记录，建议在调用API后自行在本地记录日志。

问6：如何判断地址标准化结果是否准确？
答：可以通过地址标准化控制台的“API测试和体验”功能进行在线验证。对于生产环境，建议对标准化结果进行抽样人工复核，同时结合业务场景建立准确率监控指标。如果发现结果不准确，可以尝试使用门址标准化接口或在请求中提供更完整的默认行政区划参数。