这是用户在 2024-3-27 9:41 为 https://developer.fedex.com/api/en-us/catalog/address-validation/v1/docs.html 保存的双语快照页面,由 沉浸式翻译 提供双语支持。了解如何保存?
Fedex Logo
Developer Portal  开发人员门户网站

Address Validation API 地址验证 API

Introduction 导言

The Address Validation API is a smart solution to resolve inaccurate contact details and enable faster delivery of packages with precision. This API appropriately formats the input recipient address information that closely resembles a valid address and returns a real-world address that is likely to be the one intended.
地址验证应用程序接口(Address Validation API)是一种智能解决方案,可解决联系信息不准确的问题,从而更快、更准确地投递包裹。该应用程序接口会对输入的收件人地址信息进行适当格式化,使其与有效地址非常相似,并返回一个可能是预定地址的真实地址。

The API also provides annotations about deficiencies in the input address or changes that were made to the input to arrive at that real-world address. You can use this API to validate and resolve the recipient address information before you ship a package.
该 API 还提供注释,说明输入地址中的不足之处,或为获得真实地址而对输入地址进行的更改。您可以在寄送包裹前使用此 API 验证和解析收件人地址信息。

Note: Do not use this API to determine the deliverability of an address. FedEx does not offer delivery service to every valid address. FedEx does not deliver to P.O. Boxes except via FedEx Ground® Economy (Formerly known as FedEx SmartPost®).
注意:请勿使用此 API 来确定地址是否可送达。FedEx 并不向每个有效地址提供递送服务。除非通过 FedEx Ground® Economy(前身为 FedEx SmartPost®),否则联邦快递不向邮政信箱投递。

Address Validation API Details
地址验证 API 详情

This API allows to validate and correct recipient address information before shipping a package. Accurate addresses on the shipping label will help eliminate delivery delays and additional address correction fees (due to malformed addresses).
该应用程序接口允许在发送包裹前验证和更正收件人地址信息。送货标签上的准确地址将有助于消除送货延迟和额外的地址更正费用(由于畸形地址)。

Note: 请注意:

  • Address resolution results vary by country/territory.
    地址解析结果因国家/地区而异。
  • The entered address in the request is compared with the reference data in the FedEx database and the matched address is returned.
    将请求中输入的地址与联邦快递数据库中的参考数据进行比较,然后返回匹配的地址。

Address Validation API Functionalities
地址验证 API 功能

  • Provides street level address matches.
    提供街道级地址匹配。
  • Receives monthly updates to its address database.
    每月接收地址数据库更新。
  • Distinguishes between business and residential addresses if an exact match is found.
    如果找到完全匹配的地址,则区分企业地址和住宅地址。
  • Does not currently verify suite or apartment numbers.
    目前无法核实套间或公寓编号。

Address Validation API Capabilities
地址验证 API 功能

  • Completes the incomplete recipient addresses. In some cases, Address Validation API will be able to add missing information, depending on the verification of the provided information against reference data. Address Validation API cannot add missing secondary information (i.e., apartment or suite) at this time.
    补全不完整的收件人地址。在某些情况下,地址验证 API 将能够添加缺失的信息,这取决于所提供信息与参考数据的验证情况。地址验证 API 目前无法添加缺失的次要信息(如公寓或套房)。
  • Receives monthly updates to its address database.
    每月接收地址数据库更新。
  • Corrects invalid recipient addresses. For example, correction of an incorrect postal code to agree with the remainder of the input.
    更正无效的收件人地址。例如,更正错误的邮政编码,使其与其余输入内容一致。
  • Determine whether an address is business or residential to increase the accuracy of courtesy rate quotes. Applies to U.S. and Canada addresses only.
    确定地址是商业地址还是住宅地址,以提高礼遇费率报价的准确性。仅适用于美国和加拿大地址。
  • Confirm the validity and completeness of addresses in many countries in these regions: U.S., Canada, Latin America, Europe, the Middle East and Asia Pacific. You are now able to validate domestic and international address information before shipping a package, eliminating unnecessary delivery delays and additional service fees.
    确认这些地区许多国家地址的有效性和完整性:美国、加拿大、拉丁美洲、欧洲、中东和亚太地区。现在,您可以在寄送包裹前验证国内和国际地址信息,从而避免不必要的递送延误和额外的服务费用。
  • Provides street level matches.
    提供街道级匹配。
  • Up to 100 addresses can be checked in one API request.
    一次 API 请求最多可检查 100 个地址。

Countries/Territories Supporting Address Validation API
支持地址验证 API 的国家/地区

You can use the FedEx Address Validation API in the following countries to validate and correct the recipient addresses for efficient deliveries.
您可以在以下国家/地区使用 FedEx 地址验证 API 来验证和更正收件人地址,以提高递送效率。

Antilles 安的列斯群岛 Denmark 丹麦 Panama 巴拿马
Argentina 阿根廷 Dominican Republic 多米尼加共和国 Peru 秘鲁
Aruba 阿鲁巴 Estonia 爱沙尼亚 Portugal 葡萄牙
Australia 澳大利亚 Finland 芬兰 Singapore 新加坡
Austria 奥地利 France 法国 South Africa 南非
Bahamas 巴哈马 Germany 德国 Spain 西班牙
Barbados 巴巴多斯 Greece 希腊 Sweden 瑞典
Belgium 比利时 Guatemala 危地马拉 Switzerland 瑞士
Bermuda 百慕大群岛 Hong Kong SAR, China
中国香港特别行政区
Trinidad and Tobago 特立尼达和多巴哥
Brazil 巴西 Italy 意大利 United Kingdom 英国
Canada 加拿大 Jamaica 牙买加 United States 美国
Cayman Islands 开曼群岛 Malaysia 马来西亚 Uruguay 乌拉圭
Chile 智利 Mexico 墨西哥 Venezuela 委内瑞拉
Columbia 哥伦比亚 Netherlands 荷兰 Virgin Islands 维尔京群岛
Costa Rica 哥斯达黎加 New Zealand 新西兰  
Czech Republic 捷克共和国 Norway 挪威  

 

Note: The information returned by Validate Address Request is for suggested use only.
注意:验证地址请求返回的信息仅供建议使用。

Legal Disclaimer: The data provided herein is FedEx proprietary and confidential information, provided as a courtesy at your request. No part of this data may be distributed or disclosed in any form to any third party without the written permission of FedEx. It reflects the current FedEx address-level business/residential classification in the FedEx delivery address database, and is subject to change. In furnishing this information, FedEx does not guarantee its present or future accuracy, and does not guarantee that packages shipped to these addresses will be invoiced according to the business/residential classification provided herein. Providing this information shall not be deemed to alter the terms of the relationship between the parties. See the FedEx Service Guide and any applicable account pricing agreement for terms and conditions governing FedEx shipping and charges.
法律免责声明:此处提供的数据是联邦快递专有的机密信息,应您的要求提供。未经 FedEx 书面许可,不得以任何形式向任何第三方分发或披露本数据的任何部分。这些数据反映了联邦快递递送地址数据库中当前的联邦快递地址级别的商业/住宅分类,但可能会有所更改。在提供此信息时,FedEx 并不保证其现在或将来的准确性,也不保证托运至这些地址的包裹将按照此处提供的商业/住宅分类开具发票。提供此信息不应被视为改变双方之间的关系条款。有关联邦快递托运和收费的条款和条件,请参阅《联邦快递服务指南》和任何适用的帐户定价协议。

How Address Validation API Works
地址验证 API 如何工作

Validate Address 验证地址

Use this endpoint to validate and resolve input addresses and returns real-world addresses. The address details are provided and validated in order to resolve an address. An address is stated as resolved when the input address matches the known reference data.
使用该端点验证和解析输入地址,并返回真实世界的地址。为了解析地址,需要提供并验证地址详细信息。当输入地址与已知参考数据相匹配时,地址即被解析。

The required input information associated with this request is:
与该请求相关的所需输入信息是

  • Street Lines 街道线路
  • City (Optional) 城市(可选)
  • State or Province Code (Optional)
    州或省代码(可选)
  • Postal Code (Optional) 邮政编码(可选)
  • Country Code 国家代码

Note: State code or city name is enough when customer shipping to a country which does not have a postal code.
注:如果客户寄往的国家没有邮政编码,则州代码或城市名称即可。

The Address Validation API returns a real-world address by performing the following operations on the input address:
地址验证 API 通过对输入地址执行以下操作来返回真实世界的地址:

  • As the first step, the API attempts to normalize the input address. This can include replacing common roadway identifiers such as street and parkway with their standard abbreviations such as ST and PKWY, as well as reordering components of the address. If an input address cannot be normalized, the resolved addresses returned will be the input address. Non-address values are discarded.
    第一步,应用程序接口会尝试对输入地址进行规范化处理。这包括用标准缩写(如 ST 和 PKWY)替换常用道路标识符(如街道和公园路),以及对地址中的组件重新排序。如果输入地址无法正常化,返回的解析地址将是输入地址。非地址值将被丢弃。
  • In the second step, the API attempts to standardize the normalized address by finding a possible or actual address that is likely the one intended by the user. If that standardization fails, the resolved addresses returned will be the normalized form of the input address. Refer to the elements returned to help determine the problems with the address submitted.
    在第二步中,应用程序接口会尝试通过查找一个可能的或实际的地址来使标准化地址标准化,而这个地址很可能就是用户想要的地址。如果标准化失败,返回的解析地址将是输入地址的规范化形式。请参考返回的元素,以帮助确定所提交地址的问题所在。
  • Certain elements of that normalized address will also be returned. If standardization does succeed, the resolved addresses returned will be that real-world address. In this case, various additional elements of the standardized address and information on how it was derived from the normalized address is also returned.
    该标准化地址的某些元素也将被返回。如果标准化成功,返回的解析地址将是真实世界的地址。在这种情况下,还将返回标准化地址的各种附加元素,以及如何从标准化地址导出的信息。

Address Validation API Return Values
地址验证 API 返回值

If the address returned includes the following values for the below attributes, then the address is valid:
如果返回的地址包含以下属性值,则地址有效:

  • Address State is Standardized
    地址状态标准化
  • Attributes of Resolved address are True
    已解决地址的属性为 True
  • Delivery Point Valid (DPV) is True
    交货点有效 (DPV) 为真
  • Interpolated Address is False
    插值地址为假

If these are not listed, then use the additional attributes to determine the possible problems with the address values.
如果没有列出,则使用附加属性来确定地址值可能存在的问题。

For more information on Address Attributes, see Address Attributes.
有关地址属性的更多信息,请参阅地址属性。

If the output returned customer message is INTERPOLATED.STREET.ADDRESS, then there is a chance that the address is not valid. For more information on customer message code, refer to the element description of customer message.
如果输出返回的客户信息是 INTERPOLATED.STREET.ADDRESS,则地址有可能无效。有关客户信息代码的更多信息,请参阅客户信息的元素说明。

Annotations 注释

Address Validation API returns annotations with every address validated and returned. The annotations give you information on the deficiencies if any and the changes made to the input address to arrive at that real-world address.
地址验证 API 在验证和返回每个地址时都会返回注释。这些注释会向您提供有关缺陷(如果有的话)的信息,以及为获得真实世界地址而对输入地址所做的更改。

Address Classification 地址分类

The Address Validation API uses reference data to determine the classification of a given address. The classification for a functional address is calculated independently of the validation address process and is based on feedback by operational personnel, with commercial data sources used for confirmation only.
地址验证 API 使用参考数据来确定给定地址的分类。功能地址的分类计算独立于验证地址流程,以业务人员的反馈为基础,商业数据源仅用于确认。


The Address Validation API has only four possible classifications for addresses: unknown, business, residential and mixed. All addresses begin with an 'unknown' classification and stay that way until address validation business rules determine that their classifications should change. A location only gets a 'mixed' classification if it is a multi-tenant-based address and contains both business and residential units.
地址验证 API 只有四种可能的地址分类:未知、商业、住宅和混合。所有地址一开始都是 "未知 "分类,直到地址验证业务规则决定改变其分类为止。只有同时包含商业和住宅单位的多租户地址,才会获得 "混合 "分类。

Note: FedEx Express service provides an additional address line (address line 3) for recipient addresses. This additional address information provides more complete and accurate location details improving your chances of getting accurate address.
注意:FedEx 快递服务为收件人地址提供附加地址栏(地址栏 3)。该附加地址信息提供了更完整、更准确的位置详细信息,提高了您获得准确地址的机会。

The real-world addresses are classified as follows:
现实世界的地址分类如下:

Business Address 公司地址

A business address is an address that is used to designate your principal place of business. It is where your business is supposedly operating from, but that may not always be the case.
商业地址是用来指定您的主要营业地的地址。按理说,这是您开展业务的地方,但实际情况并非总是如此。

A business address is the official location of a company's premises. It could be anything from someone's home address right up to a multi-million-dollar campus, such as those big tech companies favor and everything in between.
商业地址是公司办公场所的正式地点。它可以是某个人的家庭住址,也可以是一个价值数百万美元的园区,比如那些大型科技公司,也可以是介于两者之间的任何地方。

Residential Address 居住地址

A residential delivery charge will apply to shipments within the U.S. made to a home or private residence, including locations where a business is operated from a home. Use FedEx Home Delivery for residential delivery via FedEx Ground in 1 business day, based on distance to the destination.
在美国境内将货件递送至住宅或私人住宅,包括在住宅内经营业务的地点,将收取住宅递送费。使用联邦快递宅急送可在 1 个工作日内通过联邦快递陆运将货件送达住宅,具体时间取决于与目的地的距离。

Example: 例如

  • Rectory 教区
  • Convent 修道院
  • Parsonage 堂屋
  • Residents of multiple-unit dwellings, such as:
    多单元住宅的居民,如
    • Apartment buildings 公寓楼
    • Condominiums 共管公寓
    • College dormitories 大学宿舍
  • A residence where products are sold and/or distributed
    销售和/或分销产品的住所

Tips for Using the Address Validation API
使用地址验证 API 的提示

Following are some useful tips for using the Address Validation API:
以下是使用地址验证 API 的一些有用提示:

  • Use correct spacing: Make sure spaces are placed correctly and avoid unnecessary spaces.
    使用正确的间距:确保空格位置正确,避免不必要的空格。
  • Use correct spelling: Avoid any spelling and typographical errors. Also, make sure you have the correct usage of the number zero (0) and letter O.
    使用正确的拼写:避免任何拼写和排版错误。此外,确保正确使用数字 0 和字母 O。
  • Avoid special characters: Please refrain from using special characters not required for the address, such as periods after abbreviations (Ave vs. Ave.).
    避免使用特殊字符:请避免使用地址中不需要的特殊字符,如缩写词后面的句号(Ave vs. Ave.)。
  • Provide additional address and Street Information: By providing additional address information, you can increase the accuracy of address results.
    提供其他地址和街道信息:通过提供附加地址信息,可以提高地址结果的准确性。
    • Building or House number - 1, 1A, 1½, One
      楼号或门牌号 - 1、1A、1½、一
    • Street Name - Main, George Washington, 42nd
      街道名称 - Main, George Washington, 42 nd
    • Street Suffix - Road, Avenue, Rd, Ave
      街道后缀 - 道路、大道、Rd、Ave
  • Enter city, state/province and ZIP or postal code: Providing all three will increase the accuracy of your address results.
    输入城市、州/省和邮政编码:提供所有三项将提高地址结果的准确性。
  • Enter street and address in order: Street address elements usually follow a format starting with the building or house number followed by a pre-directional element, a street name, street type or suffix, a post-directional element, apartment designation, apartment number and/or private mailbox designation and number.
    按顺序输入街道和地址:街道地址元素的格式通常以建筑物或门牌号开头,然后是前向元素、街道名称、街道类型或后缀、后向元素、公寓名称、公寓编号和/或私人邮箱名称和编号。
  • Use correct abbreviations: The U.S. Postal Service and Canada Post has standard abbreviations for state/province, street suffix and apartment or unit designations.
    使用正确的缩写:美国邮政和加拿大邮政对州/省、街道后缀和公寓或单位名称都有标准缩写。
    • A non-standard abbreviation may cause poor search results.
      非标准缩写可能会导致搜索结果不佳。
    • If you are unsure about an abbreviation, do not use it.
      如果对缩写不确定,请勿使用。

For example: 例如

  • Building or house number such as 1, 1A, One.
    建筑物或房屋编号,如 1、1A、One。
  • Street name such as Main, George Washington, 42nd.
    街道名称,如 Main 街、George Washington 街、42 街。
  • Street suffix such as Road, Avenue, Rd, Ave.
    街道后缀,如 Road、Avenue、Rd、Ave.
  • Enter city, state/province and postal code: Providing all address information will increase the accuracy of your results. The ZIP+4 portion of the postal code is not necessary to check an address.
    输入城市、州/省和邮政编码:提供所有地址信息将提高结果的准确性。邮政编码的 ZIP+4 部分不是检查地址所必需的。
  • Use correct abbreviations: The United States Postal Service and postal authorities in other countries define standard abbreviations for state/province, street suffix, and apartment/unit designations. A nonstandard abbreviation may cause poor search results. If you are unsure about an abbreviation, do not use it.
    使用正确的缩写:美国邮政服务局和其他国家的邮政机构为州/省、街道后缀和公寓/单元名称定义了标准缩写。非标准缩写可能会导致搜索结果不佳。如果您对缩写不确定,请勿使用。
  • Consider returning the address validation response feedback to the user in order to give them the option to choose the most correct address for them.
    考虑将地址验证响应反馈返回给用户,以便让他们选择最正确的地址。

Business Rules 业务规则

  • Do not use this API to determine the package deliverability of an address. FedEx does not offer delivery service to every valid address. FedEx does not deliver to P.O. Boxes (except via FedEx Ground® Economy (Formerly known as FedEx SmartPost®).
    请勿使用此 API 来确定地址的包裹递送能力。FedEx 并不向每个有效地址提供递送服务。联邦快递不向邮政信箱派送包裹(通过 FedEx Ground® Economy(前身为 FedEx SmartPost ® 派送的包裹除外)。
  • The information returned by resolved address is for suggested use only.
    解析地址返回的信息仅供建议使用。
  • Up to 100 addresses can be checked in one request.
    一次请求最多可检查 100 个地址。
  • The minimum required fields vary among countries.
    各国要求的最低字段数各不相同。

    For example, for U.S. addresses, at least one address line and either a postal code or a city and a state code are required, but for AUS (Australia address format) addresses, the state code may be omitted even without a postal code.
    例如,对于美国地址,至少需要一个地址栏和一个邮政编码或一个城市和一个州代码,但对于 AUS(澳大利亚地址格式)地址,即使没有邮政编码,也可以省略州代码。

  • Address resolution result may vary by country/territory.
    地址解析结果可能因国家/地区而异。

Note: Address Validation API might not be applicable for all the countries. Refer the section Countries/Territories Supporting Address Validation API.
注意:地址验证 API 可能不适用于所有国家/地区。请参阅支持地址验证 API 的国家/地区部分。

Address Validation API (1.0.0)

Validate Address 验证地址

Use this endpoint to get address resolution details. These details are the outcome of validation andddd resolution of the input address. An address is stated assss resolved when the input address matches the known reference data...
使用该端点可获取地址解析详细信息。这些详细信息是输入地址的验证和解决结果。当输入地址与已知参考数据相匹配时,地址即被视为已解析...

Note: FedEx APIs do not support Cross-Origin Resource Sharing (CORS) mechanism.
注意:FedEx API 不支持跨源资源共享 (CORS) 机制。


EXPAND ALLCOLLAPSE ALL
全部展开 全部折叠
header Parameters 页眉参数
x-customer-transaction-id
string 字符串
Example: 624deea6-b709-470c-8c39-4b5511281492

This element allows you to assign a unique identifier to your transaction. This element is also returned in the reply and helps you match the request to the reply.
通过该元素,您可以为交易指定一个唯一标识符。该元素也会在回复中返回,帮助您匹配请求和回复。

content-type 内容类型
required  所需
string 字符串
Example: application/json 示例:application/json

This is used to indicate the media type of the resource. The media type is a string sent along with the file indicating format of the file.
用于指示资源的媒体类型。媒体类型是一个与文件一起发送的字符串,表示文件的格式。

x-locale
string 字符串
Example: en_US 示例:en_US

This indicates the combination of language code and country code. Click here to see Locales
这表示语言代码和国家代码的组合。单击此处查看语言区

authorization 授权
required  所需
string 字符串
Example: Bearer XXX 示例:承载器 XXX

This indicates the authorization token for the input request.
这表示输入请求的授权令牌。

Request Body schema: application/json
请求正文模式:application/json
One of
  • Full_Schema_Validate_Address
  • Address_Validation_Canada
  • Address_Validation_US
  • Address_Validation_for_Germany
  • Address_Validation_for_Italy
  • Address_Validation_for_UK
inEffectAsOfTimestamp
string 字符串

This can be used to request the characteristics of an address had at a particular time in history. This defaults to current date time (of the Address Validation System). This is useful because the AddressValidation database is dynamic and stores historical data. Characteristics such as Business/Residential indicator may change over time.
可用于查询历史上某一特定时间的地址特征。默认为(地址验证系统的)当前日期时间。这很有用,因为 AddressValidation 数据库是动态的,存储的是历史数据。商业/住宅指标等特征可能会随着时间的推移而改变。

Example: 2019-09-06 例如:2019-09-06

validateAddressControlParameters
验证地址控制参数
object 反对 (AddressResolutionControlParameters)

Specify the parameters applied to validate the address.
指定用于验证地址的参数。

addressesToValidate 要验证的地址
required  所需
Array of objects 对象数组 (ResolveContactAndAddress)

Indicate the address to be validated and resolved. This includes the address details, such as streetline, state or province code, country code and postal code.
指明需要验证和解决的地址。这包括地址详细信息,如街道线、州或省代码、国家代码和邮政编码。


Note: Up to 100 of these can be submitted in a single request.
注:一次申请最多可提交 100 份此类申请。

Responses  答复

200

Success

Response Schema: application/json
响应模式:application/json
transactionId 交易 ID
string 字符串

Unique identifier returned in the reply and helps you match the request to the reply.
回复中返回的唯一标识符,可帮助您匹配请求和回复。

Example: XXX_ORDERXXXX789
例如xxx_orderxxxx789

customerTransactionId 客户交易标识
string 字符串

This element allows you to assign a unique identifier to your transaction. This element is also returned in the reply and helps you match the request to the reply.
通过该元素,您可以为交易指定一个唯一标识符。该元素也会在回复中返回,帮助您匹配请求和回复。


Example: XXX_ORDERXXXX789
例如xxx_orderxxxx789

output 产量
object 反对 (AddressResolutionOutputVOV3)

Indicates the resolved address parameters.
表示已解析的地址参数。

400

Bad Request

401

Unauthorized

 401 未授权
403

Forbidden

404

Not Found

 404 找不到
500

Failure

 500失败
503

Service Unavailable

 503服务不可用
post 邮寄 /address/v1/addresses/resolve

Sandbox Server 沙箱服务器

https://apis-sandbox.fedex.com/address/v1/addresses/resolve

Production Server 生产服务器

https://apis.fedex.com/address/v1/addresses/resolve

Request samples - Validate Address