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/supplemental/territory_information.html。示例：“CH”（瑞士）。如果未提供区号，则根据该地址推断出来。为获得最佳性能，建议您添加区域代码（如果您知道的话）。地区不一致或重复地区可能会导致性能不佳，例如，如果 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 不会拒绝设置了此字段的请求，但信息将被舍弃，不会在响应中返回。

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

object (Verdict)

总体认定结果标记

object (Address)

与地址本身（而非地理编码）相关的信息。

object (Geocode)

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

object (AddressMetadata)

与交付情况相关的其他信息。对于发送到 Address Validation API 的每个地址，不能保证 metadata 完全填充。

object (UspsData)

由 USPS 提供的其他可交付性标记。仅在区域 US 和 PR 中提供。

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

enum (Granularity)

input 地址的粒度。这是解析输入地址的结果，不提供任何验证信号。如需了解验证信号，请参阅下文中的 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 中。例如，['street_number', 'route'] 表示输入，如“Boulder, Colorado, 80301, USA”。您可以点击此处查看可能的类型列表。

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

表示组件名称的拼写经过了细微更正，例如通过切换显示顺序有误的两个字符。这表示外观更改。

boolean

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

boolean

表示地址元素预计不会出现在给定区域的邮政地址中。我们之所以保留它，只是因为它属于输入内容的一部分。

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

string

名称文本。例如，“5th Avenue”表示街道名称，“1253”表示街道编号。

string

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

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

object (LatLng)

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

使用地点 ID 优于使用地址、纬度/经度坐标，以及 Plus 代码。在确定路线或计算行车路线路线时，使用坐标始终会导致对应点被贴近距离这些坐标最近的道路。这条路不能快速或安全地到达目的地，而且不能靠近相应酒店的接入点。此外，当某个地址经过反向地理编码后，无法保证返回的地址与原始地址一致。

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/8000 x 1/8000 度面积（约 14 x 14 米）。

string

地点的复合代码（如“33GV+HQ，Ramberg，挪威”），其中包含全局代码的后缀，并用引用实体的格式名称替换前缀。

{
  "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)

USPS 标准化地址。

string

2 位数送货代码

string

递送点验证码。此数字会添加到用于自动扫描的邮件的 delivery_point_barcode 的末尾。将 delivery_point_barcode、deliveryPointCheckDigit、邮政编码和 ZIP+4 的所有数字相加应该得到一个可被 10 整除的数字。

string

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

• Y：已针对主要号码和任何辅助号码确认 DPV 地址。
• N：无法通过 DPV 确认主号码和任何辅助号码信息。
• S：仅确认主号码的 DPV，以及未确认的辅助号码信息。
• D：之前仅确认了主号码的 DPV，但缺少辅助号码信息。

string

交付点验证中的脚注。多个脚注可以放在同一字符串中。

• AA：与 ZIP+4 文件匹配的输入地址
• A1：输入地址与 ZIP+4 文件不匹配
• BB：与 DPV（所有组件）匹配
• CC：辅助号码不匹配（存在但无效）
• N1：高层地址缺少辅助号码
• M1：缺少主电话号码
• M3：主电话号码无效
• P1：缺少输入地址 RR 或 HC 方框编号
• P3：输入地址 PO、RR 或 HC Box 号码无效
• F1：输入的地址与军事地址相匹配
• G1：输入地址与常规送货地址匹配
• U1：输入地址匹配唯一邮政编码
• PB：与 PBSA 记录匹配的输入地址
• RR：DPV 已确认的地址（含 PMB 信息）
• R1：DPV 已确认的地址，不含 PMB 信息
• R7：运营商路线 R777 或 R779 记录

string

指明地址是否为 CMRA（商业邮件接收代理机构）- 即接收客户邮件的私营企业。返回单个字符。

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

string

这个地方是空的吗？返回单个字符。

• Y：地址为空
• N：地址不是空的

string

这是非统计信息地址还是有效的地址？没有统计信息的地址是指持续被占用的地址或 USPS 不提供的地址。返回单个字符。

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

string

运营商路线代码。由 1 个字母前缀和 3 位数路线指示符组成的 4 个字符的代码。

前缀：

• 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：套件链接记录一致，商家地址已改进。
• 00：不匹配，商家地址未优化。

string

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

string

PMB（私人邮箱）编号；

string

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

• F：FIRM。这与精确记录匹配，精确记录是可用于地址的最高匹配级别。
• G：一般交付。这与常规递送记录匹配。
• H：建筑 / 公寓。这与“建筑物”或“公寓”记录相符。
• P：邮政信箱。这与邮政信箱匹配。
• R：ROUTAL ROUTE 或 HighWAY CONTRACT：匹配乡村路线或高速公路合同记录，两者可能都有关联的 Box Number 范围。
• S：STREET RECORD：与包含有效主要数字范围的街景记录相匹配。

boolean

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

string

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

如果存在此错误，可能不会填充 USPS 数据字段。

boolean

指示请求的 CASS 已处理的指示符。

{
  "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。