Method: validateAddress

{
  "revision": integer,
  "regionCode": string,
  "languageCode": string,
  "postalCode": string,
  "sortingCode": string,
  "administrativeArea": string,
  "locality": string,
  "sublocality": string,
  "addressLines": [
    string
  ],
  "recipients": [
    string
  ],
  "organization": string
}

integer

PostalAddress 的架构修订版本。除 0 之外的任何值都会导致 API 返回 INVALID_ARGUMENT 错误。

string

可选。地址的国家/地区的 CLDR 地区代码。如需了解详情，请访问 https://cldr.unicode.org/ 和 https://www.unicode.org/cldr/charts/30/批准/地区_信息.html。示例：“瑞士”表示瑞士。如果未提供地区代码，则系统会根据地址推断出来。为实现最佳效果，如果您知道区号，建议您添加区号。存在不一致或重复的地区可能会导致性能不佳，例如，如果 addressLines 已包含地区，请不要在此字段中再次提供地区代码。如需了解支持的地区，请参阅常见问题解答。

string

输入地址中的语言代码已预留为将来使用，目前会被忽略。API 会以适当的语言返回地址所在的地址。

string

可选。地址的邮政编码。并非所有国家/地区都使用或要求使用邮政编码，但在使用邮政编码时，它们可能会触发地址其他部分的额外验证（例如美国的州/邮政编码验证）。

string

可选。特定于国家/地区的额外排序代码。大多数区域都未使用此功能。在使用它的地方，此值可以是一个类似“CEDEX”的字符串，后面可能会跟一个数字（例如“CEDEX 7”），或者只有一个数字，代表“管制区代码”（牙买加），“投递区域指标”（马拉维）或“邮局指标”（例如科特迪瓦）。

string

可选。最高行政区划，用于国家或地区的邮政地址。例如，此值可以是州、省、州（俄罗斯）或县。具体来说，对于西班牙，此值为省而非自治区（例如此值为“巴塞罗那”而非“加泰罗尼亚”）。许多国家在邮政地址中不使用行政区划。例如对于瑞士，此字段应留空。

string

可选。一般是指地址的城市/城镇部分。示例：美国的城市、意大利的市镇、英国的邮镇。对于没有明确定义 locality 或者其无法很好地对应这个结构的区域，应将 locality 留空并使用 address_lines。

string

可选。地址的子级市行政区。例如，此值可以是社区、自治市/镇/区、行政区。

string

必需。描述详细地址的非结构化地址行。

由于 addressLines 中的值没有类型信息，并且有时可能在单个字段中包含多个值（例如“Austin, TX”），因此行顺序必须清晰。地址行的顺序应该是地址所在国家/地区的“信包顺序”。

地址的最小结构化表示形式包括 addressLines 中的所有信息。如果未提供 regionCode，则系统会根据地址行推断出区域。

创建仅包含 addressLines 的地址，然后进行地理编码是处理完全非结构化地址的推荐方法（而不是猜测地址的哪些部分是市行政区或行政区）。

string

请避免设置此字段。Address Validation API 目前没有使用它。尽管目前 API 不会拒绝设置了此字段的请求，但相关信息会被舍弃，并且不会在响应中返回。

string

请避免设置此字段。Address Validation API 目前没有使用它。尽管目前 API 不会拒绝设置了此字段的请求，但相关信息会被舍弃，并且不会在响应中返回。

{
  "returnEnglishLatinAddress": boolean
}

boolean

预览：返回英语的 google.maps.addressvalidation.v1.Address。如需了解详情，请参阅 google.maps.addressvalidation.v1.ValidationResult.english_latin_address。

{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  },
  "englishLatinAddress": {
    object (Address)
  }
}

object (Verdict)

总体判定标记

object (Address)

地址本身（与地理编码相对）的信息。

object (Geocode)

对地址进行地理编码的位置和地点的相关信息。

object (AddressMetadata)

与交付成果相关的其他信息。不能保证发送到 Address Validation API 的每个地址都会完整填充 metadata。

object (UspsData)

USPS 提供的额外交付标记。仅在 US 和 PR 区域提供。

object (Address)

预览版：此功能目前为正式发布前的预览版。对正式发布前产品和功能的支持可能较为有限，并且对正式发布前产品和功能的更改可能不兼容其他正式发布前版本。正式发布前的产品或功能受 Google Maps Platform 服务专用条款的约束。如需了解详情，请参阅发布阶段说明。

该地址已翻译为英文。如果地址的部分内容没有对应的英语翻译，服务则会以其他语言（使用拉丁字母）返回相应部分。如需了解如何选择备用语言，请参阅此处。如果地址的某个部分没有使用拉丁字母语言的任何翻译或音译，服务会以与该地址关联的当地语言返回该部分。

您已使用 google.maps.addressvalidation.v1.LanguageOptions.return_english_latin_address 标志启用此输出。

注意：系统不会填充 englishLatinAddress 中的 google.maps.addressvalidation.v1.Address.unconfirmed_component_types 字段和 englishLatinAddress.address_components 中的 google.maps.addressvalidation.v1.AddressComponent.confirmation_level 字段。

{
  "inputGranularity": enum (Granularity),
  "validationGranularity": enum (Granularity),
  "geocodeGranularity": enum (Granularity),
  "addressComplete": boolean,
  "hasUnconfirmedComponents": boolean,
  "hasInferredComponents": boolean,
  "hasReplacedComponents": boolean
}

enum (Granularity)

输入地址的粒度。这是解析输入地址的结果，不会给出任何验证信号。如需了解验证信号，请参阅下文中的 validationGranularity。

例如，如果输入地址包含具体的公寓编号，则此处的 inputGranularity 将为 SUB_PREMISE。如果无法匹配数据库中的公寓号或公寓号无效，validationGranularity 可能为 PREMISE 或更低。

enum (Granularity)

API 可以将地址完全验证到的粒度级别。例如，如果 validationGranularity 为 PREMISE，则表示可以验证级别为 PREMISE 或更粗略的所有地址组成部分。

您可以在 google.maps.addressvalidation.v1.Address.address_components 中找到按地址组成部分的验证结果。

enum (Granularity)

有关 geocode 粒度的信息。可理解为对经过地理编码的位置的粗略或精确程度的语义含义。

此属性偶尔可能与上面的 validationGranularity 不同。例如，我们的数据库可能会记录是否存在公寓编号，但不会记录大型公寓大楼内的公寓的精确位置。在这种情况下，validationGranularity 为 SUB_PREMISE，但 geocodeGranularity 为 PREMISE。

boolean

如果没有任何未解析的令牌、没有意外或缺失的地址组成部分，则认为该地址已完成。如需了解详情，请参阅 missingComponentTypes、unresolvedTokens 或 unexpected 字段。

boolean

至少有一个地址组成部分无法分类或进行验证，详见 google.maps.addressvalidation.v1.Address.address_components。

boolean

至少推断（添加）一个不在输入中的地址组成部分，请参阅 google.maps.addressvalidation.v1.Address.address_components 了解详情。

boolean

至少已替换一个地址组成部分，详情请参阅 google.maps.addressvalidation.v1.Address.address_components。

{
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "addressComponents": [
    {
      object (AddressComponent)
    }
  ],
  "missingComponentTypes": [
    string
  ],
  "unconfirmedComponentTypes": [
    string
  ],
  "unresolvedTokens": [
    string
  ]
}

string

后处理的地址，采用单行地址格式，遵循地址所在地区的地址格式规则。

object (PostalAddress)

后处理的地址，表示为邮政地址。

object (AddressComponent)

无序列表。经过格式化且更正后的地址的各个地址组成部分，以及验证信息。提供有关各个组件验证状态的信息。

地址组成部分不以特定方式排序。不要对列表中地址组成部分的顺序做任何假设。

string

预计会在格式正确的邮寄地址中出现，但在输入的内容中找不到的组成部分类型，并且无法推断得出。formattedAddress、postalAddress 或 addressComponents 中不存在此类型的组件。例如，对于“Boulder, Colorado, 80301, USA”等输入，例如 ['street_number', 'route']。如需查看可能的类型列表，请点击此处。

string

addressComponents 中存在但无法确认的组件类型。为方便起见，提供此字段：其内容相当于遍历 addressComponents，以查找 confirmationLevel 不为 CONFIRMED 或 inferred 标志未设置为 true 的所有组件的类型。如需查看可能的类型列表，请点击此处。

string

输入中任何无法解析的令牌。这可能是未被识别为地址有效部分的输入（例如，在“123235253253 Main St, San Francisco, CA, 94105”等输入中，未解析的令牌可能类似于 ["123235253253"]，因为它不像是有效的门牌号）。

{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}

object (ComponentName)

此组件的名称。

string

地址组成部分的类型。请参阅表 2：地点服务返回的其他类型，了解可能的类型列表。

enum (ConfirmationLevel)

表示我们对于组件正确的确定程度。

boolean

表示该组成部分不在输入范围内，但我们根据地址推断得出该组成部分，认为应该为完整地址提供该组成部分。

boolean

表示更正组件名称中的拼写错误。API 不一定总能标记出一个拼写变体到另一个拼写变体的变化，例如将“centre”更改为“center”时。系统也不会始终标记常见的错别字，例如，将“Amphitheater Pkwy”更改为“Amphitheatre Pkwy”时。

boolean

表示组件名称已替换为完全不同的名称，例如将错误的邮政编码替换为正确的地址。这并非外观上的变化，而是输入组件已更改为其他组件。

boolean

表示不应出现在指定地区的邮政地址中的地址组成部分。我们保留它只是因为这是意见部分。

{
  "text": string,
  "languageCode": string
}

string

名称文本。例如，“第五大道”表示街道名称，“1253”表示门牌号。

string

BCP-47 语言代码。如果组件名称没有与语言（如门牌号）相关联，则不会显示此属性。

{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}

object (LatLng)

输入的经过地理编码的位置。

相较于使用地址、纬度/经度坐标或 Plus 代码，首选使用地点 ID。在设置路线或计算行车路线时使用坐标，总是会使该点与最接近这些坐标的道路对应。此道路不得快速或安全地通往目的地，也不得靠近住所的入口。此外，即使对某个位置进行反向地理编码，也无法保证返回的地址与原始地址一致。

object (PlusCode)

与 location 对应的 Plus 代码。

object (Viewport)

经过地理编码的地点的边界。

number

经过地理编码的地点的尺寸（以米为单位）。这是对经过地理编码的位置粗略程度的另一种衡量方式，但只是物理尺寸，而不是语义意义。

string

此输入地理编码所指向的地点的 PlaceID。

如需详细了解地点 ID，请参阅此处。

string

输入经过地理编码的地点类型。例如，['locality', 'political']。完整的类型列表请点击此处。

{
  "latitude": number,
  "longitude": number
}

number

纬度（以度为单位）。它必须在 [-90.0, +90.0] 范围内。

number

经度（以度为单位）。它必须在 [-180.0, +180.0] 范围内。

{
  "globalCode": string,
  "compoundCode": string
}

string

地点的全局（完整）代码，例如“9FWM33GV+HQ”，表示面积为 1/8000x1/8000 度（约 14x14 米）。

string

地点的复合代码，例如“33GV+HQ, Ramberg, Norway”，其中包含全局代码的后缀，并将前缀替换为参考实体的格式化名称。

{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}

object (LatLng)

必需。视口的低点。

object (LatLng)

必需。视口的高点。

{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}

boolean

表明这是商家的地址。如果未设置，则表示值未知。

boolean

表示邮政信箱的地址。如果未设置，则表示值未知。

boolean

表明这是住宅的地址。如果未设置，则表示值未知。

{
  "standardizedAddress": {
    object (UspsAddress)
  },
  "deliveryPointCode": string,
  "deliveryPointCheckDigit": string,
  "dpvConfirmation": string,
  "dpvFootnote": string,
  "dpvCmra": string,
  "dpvVacant": string,
  "dpvNoStat": string,
  "carrierRoute": string,
  "carrierRouteIndicator": string,
  "ewsNoMatch": boolean,
  "postOfficeCity": string,
  "postOfficeState": string,
  "abbreviatedCity": string,
  "fipsCountyCode": string,
  "county": string,
  "elotNumber": string,
  "elotFlag": string,
  "lacsLinkReturnCode": string,
  "lacsLinkIndicator": string,
  "poBoxOnlyPostalCode": boolean,
  "suitelinkFootnote": string,
  "pmbDesignator": string,
  "pmbNumber": string,
  "addressRecordType": string,
  "defaultAddress": boolean,
  "errorMessage": string,
  "cassProcessed": boolean
}

object (UspsAddress)

美国邮政服务标准化地址。

string

2 位数的投递点代码

string

投递点验证码。对于机械扫描的邮件，此编号会添加到 delivery_point_barcode 的末尾。将 delivery_point_barcode、deliveryPointCheckDigit、postal code 和 ZIP+4 的所有数字加在一起，得出的结果应是一个可被 10 整除的数字。

string

DPV 确认的可能值。返回单个字符。

• Y：地址已通过 DPV 确认主号码和任何辅助号码。
• N：未能确认主要号码和任何辅助号码信息。
• S：仅主号码的 DPV 已确认，辅助号码信息存在，但未确认。
• D：仅主号码的 DPV 已确认，辅助号码信息缺失。

string

送货点验证的脚注。多个脚注可以在同一字符串中串联。

• AA：与 ZIP+4 文件匹配的输入地址
• A1：输入地址与 ZIP+4 文件不匹配
• BB：与 DPV（所有组成部分）匹配
• CC：次要号码不匹配（存在但无效）
• N1：高层地址缺少辅助号码
• M1：缺少主号码
• M3：主号码无效
• P1：输入地址 RR 或帮助中心编号缺失
• P3：输入地址的 PO、RR 或 HC Box 编号无效
• F1：输入地址与军方地址匹配
• G1：与一般配送地址匹配的输入地址
• U1：输入地址与唯一的邮政编码匹配
• PB：与 PBSA 记录匹配的输入地址
• RR：DPV 已确认的地址（包含 PMB 信息）
• R1：DPV 已确认的地址，不含 PMB 信息
• R7：运营商 Route R777 或 R779 记录

string

表明地址是否属于商业邮件接收代理机构 (CMRA)，即为客户接收邮件的私营企业。返回单个字符。

• Y：地址是 CMRA
• N：地址不是 CMRA

string

这个地方是否有空？返回单个字符。

• Y：地址为空
• N：地址为空

string

这是一个无统计数据的地址，还是有效地址？无统计地址是指非持续有人的地址或 USPS 不提供服务的地址。返回单个字符。

• Y：地址无效
• N：地址有效

string

运输公司路线代码。由 1 个字母前缀及 3 位数路线指示符组成的四字符代码。

前缀：

• C：运营商路线（或城市路线）
• R：乡村公路
• H：公路约定路线
• B：邮政信箱部分
• G：常规投放单元

string

运营商航线速率排序指示器。

boolean

递送地址可以匹配，但 EWS 文件表明即将提供完全匹配的结果。

string

邮局主要城市。

string

主要邮局所在州。

string

城市缩写。

string

FIPS 国家/地区代码。

string

郡/县名称。

string

增强型旅行线路 (eLOT) 编号。

string

eLOT 升序/降序标记 (A/D)。

string

LACSLink 返回代码。

string

LACSLink 指示器。

boolean

仅限邮政信箱中的邮政编码。

string

将街道或高楼记录与套房信息进行匹配的脚注。如果找到匹配的商家名称，则返回辅助号码。

• A：SuiteLink 记录一致，商家地址已得到改进。
• 00：不匹配，商家地址未改进。

string

PMB（私人邮箱）单元指示符。

string

PMB（私人邮箱）号码；

string

与输入地址匹配的地址记录的类型。

• F：FIRM。这与公司记录匹配，这是与地址最接近的匹配级别。
• G：常规传送。这与一般递送记录匹配。
• H：BUILDING / APARTMENT。这与“建筑物”或“公寓”记录相匹配。
• P：发布邮箱。此地址与邮政信箱一致。
• R：“公路”或“公路”合同：这匹配“乡村路线”或“公路合同”记录，这两者都有关联的箱号范围。
• S：STREET RECORD：与包含有效主号码范围的街道记录匹配。

boolean

表示已找到默认地址，但存在更具体的地址。

string

检索 USPS 数据时出现的错误消息。当 USPS 处理因检测到人为创建的地址而暂停时，此字段将填充数据。

出现此错误时，系统可能不会填充 USPS 数据字段。

boolean

指示请求已处理完毕的指示符。

{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}

string

第一个地址行。

string

公司名称。

string

第二行地址。

string

波多黎各城市化名称。

string

城市 + 省/自治区/直辖市 + 邮政编码。

string

城市名称。

string

由 2 个字母组成的省/自治区/直辖市代码。

string

邮政编码，例如 10009。

string

扩展 4 位数邮政编码，例如 5023。