- HTTP 请求
- 请求正文
- 响应正文
- PostalAddress
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- LanguageOptions
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- ValidationResult
- 判定
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 粒度
- 地址
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- AddressComponent
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- ComponentName
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- ConfirmationLevel
- 地理编码
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- LatLng
- PlusCode
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 视口
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- AddressMetadata
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- UspsData
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- UspsAddress
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
验证地址。
HTTP 请求
POST https://addressvalidation.googleapis.com/v1:validateAddress
网址采用 gRPC 转码语法。
请求正文
请求正文中包含结构如下的数据:
JSON 表示法 |
---|
{ "address": { object ( |
字段 | |
---|---|
address |
必需。要验证的地址。应通过 此输入字段的总长度不得超过 280 个字符。 如需了解支持的地区,请点击此处。 输入地址中的 Address Validation API 会忽略 |
previousResponseId |
对于第一个地址验证请求,此字段必须为空。如果需要更多请求来完全验证单个地址(例如,如果用户在初始验证后进行的更改需要重新验证),则每个后续请求都必须使用验证序列中第一个响应中的 |
enableUspsCass |
启用 USPS CASS 兼容模式。这只会影响 建议使用组件化 |
languageOptions |
可选。预览版:此功能目前为正式发布前的预览版。正式发布前的产品和功能获得的支持可能较为有限,并且对其作出的更改可能不兼容其他正式发布前版本。正式发布前的产品或功能受《Google Maps Platform 服务专用条款》约束。如需了解详情,请参阅发布阶段说明。 启用 Address Validation API,以在响应中包含其他信息。 |
sessionToken |
可选。用于标识“自动补全”会话以便进行结算的字符串。必须是网址和文件名安全 base64 字符串,长度不超过 36 个 ASCII 字符。否则,系统会返回 INVALID_ARGUMENT 错误。 用户执行自动补全查询时,会话开始,当用户选择地点并调用地点详情或地址验证时,会话结束。每个会话可以有多个“自动补全”查询,后跟一个“地点详情”或“地址验证”请求。一个会话内用于每个请求的凭据必须属于同一个 Google Cloud 控制台项目。会话结束后,令牌将失效;您的应用必须为每个会话生成一个新的令牌。如果省略 注意:地址验证功能只能在使用 Autocomplete(新)API(而非 Autocomplete API)的会话中使用。如需了解详情,请参阅 https://developers.google.com/maps/documentation/places/web-service/session-pricing。 |
响应正文
对地址验证请求的响应。
如果成功,响应正文将包含结构如下的数据:
JSON 表示法 |
---|
{
"result": {
object ( |
字段 | |
---|---|
result |
地址验证的结果。 |
responseId |
用于标识此回答的 UUID。如果需要重新验证地址,则此 UUID 必须随新请求一起提交。 |
PostalAddress
表示邮政地址,例如邮政递送或付款地址。给定邮政地址时,邮政服务可以将物品投递到处所、邮政信箱或其他投递地点。此对象不模拟地理位置(道路、城镇、山区)。
在典型的使用场景中,地址将通过用户输入或导入现有数据来创建,具体取决于进程的类型。
有关输入/修改地址的建议:- 使用支持国际化的地址微件,例如 https://github.com/google/libaddressinput。不应向用户显示用于输入或修改该字段的其他国家/地区对应的界面元素。
如需详细了解如何使用此架构,请参阅:https://support.google.com/business/answer/6397478
JSON 表示法 |
---|
{ "revision": integer, "regionCode": string, "languageCode": string, "postalCode": string, "sortingCode": string, "administrativeArea": string, "locality": string, "sublocality": string, "addressLines": [ string ], "recipients": [ string ], "organization": string } |
字段 | |
---|---|
revision |
|
regionCode |
可选。地址的国家/地区的 CLDR 地区代码。如需了解详情,请参阅 https://cldr.unicode.org/ 和 https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html。示例:“CH”。如果未提供区号,系统将根据地址推断出该区号。为获得最佳效果,如果您知道区域代码,建议您添加此代码。地区不一致或重复可能会导致性能不佳,例如,如果 |
languageCode |
输入地址中的语言代码是为将来使用而预留的,目前会被忽略。API 会以地址所在位置的相应语言返回地址。 |
postalCode |
可选。地址的邮政编码。并非所有国家/地区都使用或要求使用邮政编码,但在使用邮政编码时,它们可能会触发地址其他部分的额外验证(例如美国的州/邮政编码验证)。 |
sortingCode |
可选。特定于国家/地区的额外排序代码。大多数区域都未使用此功能。在使用它的地方,此值可以是一个类似“CEDEX”的字符串,后面可能会跟一个数字(例如“CEDEX 7”),或者只有一个数字,代表“管制区代码”(牙买加),“投递区域指标”(马拉维)或“邮局指标”(例如科特迪瓦)。 |
administrativeArea |
可选。最高行政区划,用于国家或地区的邮政地址。例如,此值可以是州、省、州(俄罗斯)或县。具体来说,对于西班牙,此值为省而非自治区(例如此值为“巴塞罗那”而非“加泰罗尼亚”)。许多国家在邮政地址中不使用行政区划。例如对于瑞士,此字段应留空。 |
locality |
可选。一般是指地址的城市/城镇部分。示例:美国的城市、意大利的市镇、英国的邮镇。对于没有明确定义 locality 或者其无法很好地对应这个结构的区域,应将 locality 留空并使用 address_lines。 |
sublocality |
可选。地址的子级市行政区。例如,此值可以是社区、自治市/镇/区、行政区。 |
addressLines[] |
必需。描述详细地址的非结构化地址行。 |
recipients[] |
请避免设置此字段。Address Validation API 目前未使用它。尽管 API 目前不会拒绝设置了此字段的请求,但此信息将被舍弃,并且不会在响应中返回。 |
organization |
请避免设置此字段。Address Validation API 目前未使用它。尽管 API 目前不会拒绝设置了此字段的请求,但此信息将被舍弃,并且不会在响应中返回。 |
LanguageOptions
预览版:此功能目前为正式发布前的预览版。正式发布前的产品和功能获得的支持可能较为有限,并且对其作出的更改可能不兼容其他正式发布前版本。正式发布前的产品或功能受《Google Maps Platform 服务专用条款》约束。如需了解详情,请参阅发布阶段说明。
启用 Address Validation API,以在响应中包含其他信息。
JSON 表示法 |
---|
{ "returnEnglishLatinAddress": boolean } |
字段 | |
---|---|
returnEnglishLatinAddress |
预览:返回英语 |
ValidationResult
地址验证的结果。
JSON 表示法 |
---|
{ "verdict": { object ( |
字段 | |
---|---|
verdict |
总体判定标志 |
address |
有关地址本身(而不是地理编码)的信息。 |
geocode |
该地址经过地理编码的位置和地点的相关信息。 |
metadata |
与可递送相关的其他信息。对于发送到 Address Validation API 的每个地址,系统不一定会完整填充 |
uspsData |
USPS 提供的额外可递送性标志。仅在 |
englishLatinAddress |
预览版:此功能目前为正式发布前的预览版。正式发布前的产品和功能获得的支持可能较为有限,并且对其作出的更改可能不兼容其他正式发布前版本。正式发布前的产品或功能受《Google Maps Platform 服务专用条款》约束。如需了解详情,请参阅发布阶段说明。 翻译成英文的地址。 翻译后的地址不可重复使用作为 API 输入。服务提供这些信息,以便用户能够使用母语来确认或拒绝对最初提供的地址的验证。 如果地址的一部分没有英语翻译,该服务会以使用拉丁字母的备用语言返回该部分。请参阅此处,了解如何选择备用语言。如果地址的这部分内容没有任何使用拉丁字母的语言的翻译或音译,该服务会以与该地址关联的当地语言返回这部分。 使用 注意: |
判定
地址验证结果和地理编码的简要概览。
JSON 表示法 |
---|
{ "inputGranularity": enum ( |
字段 | |
---|---|
inputGranularity |
input 地址的粒度。这是解析输入地址的结果,并不提供任何验证信号。如需了解验证信号,请参阅下面的 例如,如果输入地址包含具体的公寓号,则此处的 |
validationGranularity |
API 能够对地址进行全面验证的粒度级别。例如,如果 您可以在 |
geocodeGranularity |
有关 此值偶尔可能与上面的 |
addressComplete |
如果没有任何未解析的令牌、意外或缺失的地址组成部分,则相应地址会被视为完整地址。如果未设置,则表示值为 |
hasUnconfirmedComponents |
至少有一个地址组成部分无法分类或验证,详情请参阅 |
hasInferredComponents |
至少有一个推断(添加)的地址组成部分不在输入内容中。如需了解详情,请参阅 |
hasReplacedComponents |
至少替换了一个地址组成部分,如需了解详情,请参阅 |
粒度
地址或地理编码可以具有的各种精细度。当用于表示地址的粒度时,这些值用来表示地址标识邮寄目的地的精细程度。例如,诸如“123 Main Street, Redwood City, CA, 94061”之类的地址。用于标识 PREMISE
,而诸如“Redwood City, CA, 94061”之类的内容用于标识 LOCALITY
。但是,如果我们找不到“主街 123 号”的地理编码,在 Redwood City,返回的地理编码可能是 LOCALITY
粒度,即使地址更精确。
枚举 | |
---|---|
GRANULARITY_UNSPECIFIED |
默认值。此值未使用。 |
SUB_PREMISE |
楼下楼层结果,例如公寓。 |
PREMISE |
建筑物级结果。 |
PREMISE_PROXIMITY |
近似地表示地址的建筑物级位置的地理编码。 |
BLOCK |
地址或地理编码表示一个街区。仅在具有块级寻址的区域(例如日本)中使用。 |
ROUTE |
地理编码或地址用于细化路线,例如街道、道路或公路。 |
OTHER |
所有其他粒度(由于无法交付而分桶在一起)。 |
地址
经过后处理的地址的详细信息。后处理包括更正地址中拼写错误的部分、更换错误的部分和推断缺失的部分。
JSON 表示法 |
---|
{ "formattedAddress": string, "postalAddress": { object ( |
字段 | |
---|---|
formattedAddress |
经过后处理的地址,按照地址所在地区的地址格式规则,采用单行地址格式。 |
postalAddress |
以邮政地址表示的经过后处理的地址。 |
addressComponents[] |
无序列表。设置了格式的更正后地址的各个地址组成部分,以及验证信息。这样可以提供有关各个组件的验证状态的信息。 地址组成部分没有以特定方式排序。请勿对列表中地址组成部分的顺序做出任何假设。 |
missingComponentTypes[] |
某些组件属于以下类型:应该出现在格式正确的邮寄地址中,但在输入内容中找不到,且无法推断出的组件类型。 |
unconfirmedComponentTypes[] |
|
unresolvedTokens[] |
输入内容中无法解析的任何令牌。这可能是未被识别为地址有效部分的输入(例如,在“123235253253 Main St, San Francisco, CA, 94105”这样的输入中,未解析的令牌可能类似于 |
AddressComponent
表示地址组成部分,例如街道、城市或州/省。
JSON 表示法 |
---|
{ "componentName": { object ( |
字段 | |
---|---|
componentName |
此组件的名称。 |
componentType |
地址组成部分的类型。有关可能类型的列表,请参阅表 2:地点服务返回的其他类型。 |
confirmationLevel |
表示我们确定组件正确的程度。 |
inferred |
表示该组成部分不是输入内容的一部分,但我们根据地址位置推断出该组成部分,并认为应当针对完整地址提供该组成部分。 |
spellCorrected |
表示更正组件名称中的拼写错误。API 并不总是标记不同拼写变体之间的更改,例如在更改“centre”时移动到“center”它也不会总是标记常见的拼写错误,例如在更改“Amphitheater Pkwy”时前往“Amphitheatre Pkwy” |
replaced |
表示组件名称已替换为完全不同的名称,例如,将错误的邮政编码替换为地址正确的邮政编码。这并不是一个界面外观上的变化,已对输入组件进行了更改。 |
unexpected |
表示指定地区的邮政地址中不应存在的地址组成部分。我们之所以将其保留下来,只是因为它是输入内容的一部分。 |
ComponentName
组件名称的封装容器。
JSON 表示法 |
---|
{ "text": string, "languageCode": string } |
字段 | |
---|---|
text |
名称文本。例如:"第五大道"输入街道名称,或输入“1253”查找门牌号。 |
languageCode |
BCP-47 语言代码。如果组件名称未与语言(例如门牌号)相关联,则不会显示此字段。 |
ConfirmationLevel
确认级别的不同可能值。
枚举 | |
---|---|
CONFIRMATION_LEVEL_UNSPECIFIED |
默认值。此值未使用。 |
CONFIRMED |
我们能够验证该组成部分是否存在,以及在地址的其余部分是否合理。 |
UNCONFIRMED_BUT_PLAUSIBLE |
此组成部分无法确认,但确实存在。例如,某个街道上未知的有效门牌号。 |
UNCONFIRMED_AND_SUSPICIOUS |
此组件未经确认,很可能有误。例如,某个社区与地址的其他部分不符。 |
地理编码
包含对输入进行地理编码的地点的相关信息。
JSON 表示法 |
---|
{ "location": { object ( |
字段 | |
---|---|
location |
输入的经过地理编码的位置。 使用地点 ID 而非地址、纬度/经度坐标或 Plus 代码。在确定路线或计算行车路线时使用坐标值,总会让相应点与最接近这些坐标的道路对应起来。此道路可能既不能快速或安全地通向目的地,也可能不靠近物业的入口。此外,对某个位置进行反向地理编码时,无法保证返回的地址与原始地址一致。 |
plusCode |
与 |
bounds |
经过地理编码的地点的边界。 |
featureSizeMeters |
经过地理编码的地点的大小(以米为单位)。这是对地理编码位置的粗略程度的另一种衡量方式,但以物理大小而非语义含义为准。 |
placeId |
此输入地理编码到的地点的 PlaceID。 如需详细了解地点 ID,请参阅此处。 |
placeTypes[] |
对输入进行地理编码到的地点类型。例如, |
LatLng
表示纬度/经度对的对象。该对象以一对双精度数表示,分别代表纬度度数和经度度数。除非另有说明,否则该对象必须符合 WGS84 标准。值必须介于标准化范围内。
JSON 表示法 |
---|
{ "latitude": number, "longitude": number } |
字段 | |
---|---|
latitude |
纬度(以度为单位)。它必须在 [-90.0, +90.0] 范围内。 |
longitude |
经度(以度为单位)。它必须在 [-180.0, +180.0] 范围内。 |
PlusCode
Plus Code (http://plus.codes) 是采用两种格式的位置引用:定义 14mx14 米(1/8000 度)或更小矩形的全局代码,以及将前缀替换为引用位置的复合代码。
JSON 表示法 |
---|
{ "globalCode": string, "compoundCode": string } |
字段 | |
---|---|
globalCode |
地点的全局(完整)代码,例如“9FWM33GV+HQ”,表示 1/8000 x 1/8000 度区域(约 14 x 14 米)。 |
compoundCode |
地方的复合代码,例如“33GV+HQ, Ramberg, Norway”,其中包含全局代码的后缀,并将前缀替换为参考实体的格式化名称。 |
视口
经纬度视口,表示为两个对角线相对的 low
和 high
点。视口被视为封闭区域,即包含其边界。纬度边界必须介于 -90 度(含)到 90 度(含)之间,经度边界必须介于 -180 度(含)180 度(含)之间。各种情况包括:
如果
low
=high
,视口由该单点组成。如果
low.longitude
>high.longitude
,则经度范围会反转(视口与 180 度经度线相交)。如果
low.longitude
= -180 度,high.longitude
= 180 度,视口将包含所有经度。如果
low.longitude
= 180 度,high.longitude
= -180 度,则经度范围为空。如果
low.latitude
>high.latitude
,纬度范围为空。
low
和 high
都必须填充,并且表示的框不得为空(如上述定义所指定)。视口为空会导致错误。
例如,以下视口将纽约市完全包围:
{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }
JSON 表示法 |
---|
{ "low": { object ( |
字段 | |
---|---|
low |
必需。视口的低点。 |
high |
必需。视口的高点。 |
AddressMetadata
地址的元数据。对于发送到 Address Validation API 的每个地址,系统不一定会完整填充 metadata
。
JSON 表示法 |
---|
{ "business": boolean, "poBox": boolean, "residential": boolean } |
字段 | |
---|---|
business |
表明这是商家地址。如果未设置,则表示值未知。 |
poBox |
指明邮政信箱的地址。如果未设置,则表示值未知。 |
residential |
表明这是居住地的地址。如果未设置,则表示值未知。 |
UspsData
地址的 USPS 数据。对于发送到 Address Validation API 的每个美国或公共地址,我们不保证会完整填充 uspsData
。如果您使用 uspsData 作为响应的主要部分,建议您在响应中集成备份地址字段。
JSON 表示法 |
---|
{
"standardizedAddress": {
object ( |
字段 | |
---|---|
standardizedAddress |
USPS 标准化地址。 |
deliveryPointCode |
2 位数的配送积分代码 |
deliveryPointCheckDigit |
配送点验证码。对于采用机械扫描的邮件,此编号会添加到 delivery_point_barcode 的末尾。将 delivery_point_barcode、deliveryPointCheckDigit、邮政编码和 ZIP+4 的所有数字相加,得到一个可被 10 整除的数字。 |
dpvConfirmation |
DPV 确认的可能值。返回单个字符或不返回任何值。
|
dpvFootnote |
送达点验证的脚注。多个脚注可以在同一字符串中串联在一起。
|
dpvCmra |
指明地址是否属于 CMRA(商业邮件接收机构),即为客户接收邮件的私营企业。返回单个字符。
|
dpvVacant |
这个地方是空的吗?返回单个字符。
|
dpvNoStat |
此地址是没有统计信息的地址还是有效地址?没有统计地址是指未被持续使用的地址或 USPS 不提供服务的地址。返回单个字符。
|
dpvNoStatReasonCode |
表示 NoStat 类型。以整数形式返回原因代码。
|
dpvDrop |
标记表示邮件递送到站点中的单个可接收设备。返回单个字符。
|
dpvThrowback |
表示邮件未递送到街道地址。返回单个字符。
|
dpvNonDeliveryDays |
标记表示并非一周的每一天都执行邮件递送。返回单个字符。
|
dpvNonDeliveryDaysValues |
用于标识未投放日期的整数。可以使用位标志询问该日期:0x40 – 星期日是无法送达的日 0x20 – 星期一是无法送达的日 0x10 – 星期二是无法送达的日 0x08 – 星期三是无法送达的日 0x04 – 星期四是无法送达的日 0x02 – 星期五是无法送达的日 |
dpvNoSecureLocation |
该标记表示门可以进入,但出于安全考虑,包裹不会寄出。返回单个字符。
|
dpvPbsa |
表示地址与 PBSA 记录匹配。返回单个字符。
|
dpvDoorNotAccessible |
标记指明了 USPS 无法敲门递送邮件的地址。返回单个字符。
|
dpvEnhancedDeliveryCode |
表示有多个 DPV 返回代码对该地址有效。返回单个字符。
|
carrierRoute |
运输公司路线代码。由 1 个字母前缀和 3 位数路线指示符组成的四位字符代码。 前缀:
|
carrierRouteIndicator |
运营商路由费率排序指示器。 |
ewsNoMatch |
送货地址可匹配,但 EWS 文件显示很快就能使用完全匹配的地址。 |
postOfficeCity |
主要邮局城市。 |
postOfficeState |
主要邮局州。 |
abbreviatedCity |
城市的缩写名称。 |
fipsCountyCode |
FIPS 郡/县代码。 |
county |
郡/县名称。 |
elotNumber |
增强型旅行路线 (eLOT) 号码。 |
elotFlag |
eLOT 升序/降序标志 (A/D)。 |
lacsLinkReturnCode |
LACSLink 返回代码。 |
lacsLinkIndicator |
LACSLink 指示器。 |
poBoxOnlyPostalCode |
仅限邮政信箱的邮政编码。 |
suitelinkFootnote |
用于将街道或高层记录与套房信息进行匹配的脚注。如果找到商家名称匹配项,则返回次要号码。
|
pmbDesignator |
PMB(私人邮箱)单元标识名。 |
pmbNumber |
PMB(私人邮箱)号码; |
addressRecordType |
与输入地址匹配的地址记录类型。
|
defaultAddress |
表明找到了默认地址,但存在更具体的地址的指示符。 |
errorMessage |
检索 USPS 数据时出现的错误消息。当 USPS 处理因检测到人为创建的地址而被暂停时,系统会填充此字段。 出现此错误时,系统可能不会填充 USPS 数据字段。 |
cassProcessed |
表明请求已由 CASS 处理的指示符。 |
UspsAddress
美国地址的 USPS 表示。
JSON 表示法 |
---|
{ "firstAddressLine": string, "firm": string, "secondAddressLine": string, "urbanization": string, "cityStateZipAddressLine": string, "city": string, "state": string, "zipCode": string, "zipCodeExtension": string } |
字段 | |
---|---|
firstAddressLine |
第一个地址行。 |
firm |
公司名称。 |
secondAddressLine |
第二行地址。 |
urbanization |
波多黎各城市化名称。 |
cityStateZipAddressLine |
城市 + 州/省/自治区/直辖市 + 邮政编码。 |
city |
城市名称。 |
state |
由 2 个字母组成的州代码。 |
zipCode |
邮政编码(例如)10009。 |
zipCodeExtension |
4 位数邮政编码扩展,例如5023。 |