Method: validateAddress

验证地址。

HTTP 请求

POST https://addressvalidation.googleapis.com/v1:validateAddress

网址采用 gRPC 转码语法。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "address": {
    object (PostalAddress)
  },
  "previousResponseId": string,
  "enableUspsCass": boolean,
  "languageOptions": {
    object (LanguageOptions)
  },
  "sessionToken": string
}
字段
address

object (PostalAddress)

必需。要验证的地址。不带格式的地址应通过 addressLines 提交。

此输入中的字段总长度不得超过 280 个字符。

您可以在此处找到受支持的地区。

输入地址中的 languageCode 值是预留供日后使用的，目前会被忽略。系统会根据其识别出的给定地址的首选语言来填充经过验证的地址结果。

Address Validation API 会忽略 recipients 和 organization 中的值。这些字段中的所有值都将被舍弃，不会返回。请勿设置这些值。
previousResponseId

string

对于首次地址验证请求，此字段必须为空。如果需要发出更多请求才能完全验证单个地址（例如，如果用户在初始验证后所做的更改需要重新验证），则每个后续请求都必须使用验证序列中第一个响应中的 responseId 填充此字段。
enableUspsCass

boolean

启用 USPS CASS 兼容模式。这只会影响 google.maps.addressvalidation.v1.ValidationResult 的 google.maps.addressvalidation.v1.ValidationResult.usps_data 字段。注意：对于启用了 USPS CASS 的波多黎各地址请求，address 的 google.type.PostalAddress.region_code 必须提供为“PR”，或者 address 的 google.type.PostalAddress.administrative_area 必须提供为“Puerto Rico”（不区分大小写）或“PR”。

建议使用组件化 address，或者至少指定两个 google.type.PostalAddress.address_lines，其中第一行包含门牌号和街道名称，第二行包含城市、州/省/直辖市/自治区和邮政编码。
languageOptions

object (LanguageOptions)

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

让 Address Validation API 能够在响应中添加其他信息。
sessionToken

string

可选。用于标识自动补全会话的字符串，以便进行结算。必须是网址和文件名安全的 base64 字符串，长度不得超过 36 个 ASCII 字符。否则，系统会返回 INVALID_ARGUMENT 错误。

会话在用户发出自动补全查询时开始，并在用户选择地点并发出对“地点详情”或“地址验证”的调用时结束。在每个会话中，用户可以输入多项自动补全查询，并最终发出一个地点详情或地址验证请求。在一个会话中，每个请求使用的凭据都必须属于同一 Google Cloud 控制台项目。会话结束后，令牌将失效；您的应用必须为每个会话生成一个新的令牌。如果您省略 sessionToken 参数或重复使用会话令牌，系统会按未提供会话令牌的情况为会话计费（每个请求均单独结算）。

注意：Address Validation 只能在使用 Autocomplete（新版）API（而非 Autocomplete API）的会话中使用。如需了解详情，请访问 https://developers.google.com/maps/documentation/places/web-service/session-pricing。

响应正文

对地址验证请求的响应。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "result": {
    object (ValidationResult)
  },
  "responseId": string
}
字段
result

object (ValidationResult)

地址验证结果。
responseId

string

用于标识此响应的 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

integer

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

string

可选。地址的国家/地区的 CLDR 地区代码。如需了解详情，请参阅 https://cldr.unicode.org/ 和 https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html。例如：瑞士的地区代码为“CH”。如果未提供地区代码，系统会根据地址推断出地区代码。为获得最佳效果，建议您添加地区代码（如果您知道）。区域不一致或重复可能会导致效果不佳，例如，如果 addressLines 已包含相应区域，请勿在此字段中再次提供该区域代码。如需了解支持的地区，请参阅常见问题解答。
languageCode

string

输入地址中的语言代码预留以供日后使用，目前会被忽略。该 API 会以相应地址所在地所用语言返回地址。
postalCode

string

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

string

可选。特定于国家/地区的额外排序代码。大多数区域都未使用此功能。在使用时，此值可以是字符串（例如“CEDEX”），可选地后跟数字（例如“CEDEX 7”），也可以是单独的数字，表示“部门代码”（牙买加）、“配送区域指标”（马拉维）或“邮局指标”（科特迪瓦）。
administrativeArea

string

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

string

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

string

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

string

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

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

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

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

string

请避免设置此字段。Address Validation API 目前不使用它。虽然目前该 API 不会拒绝设置了此字段的请求，但系统会舍弃相应信息，不会在响应中返回。
organization

string

请避免设置此字段。Address Validation API 目前不使用它。虽然目前该 API 不会拒绝设置了此字段的请求，但系统会舍弃相应信息，不会在响应中返回。

LanguageOptions

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

让 Address Validation API 能够在响应中添加其他信息。

JSON 表示法 
{
  "returnEnglishLatinAddress": boolean
}
字段
returnEnglishLatinAddress

boolean

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

ValidationResult

地址验证结果。

JSON 表示法 
{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  },
  "englishLatinAddress": {
    object (Address)
  }
}
字段
verdict

object (Verdict)

总体判定标志
address

object (Address)

与地理编码相对，与地址本身相关的信息。
geocode

object (Geocode)

与地址经过地理编码后对应的地点和地理位置相关的信息。
metadata

object (AddressMetadata)

与可送达性相关的其他信息。无法保证为发送到 Address Validation API 的每个地址都完全填充 metadata。
uspsData

object (UspsData)

USPS 提供的额外可送达性标志。仅在区域 US 和 PR 中提供。
englishLatinAddress

object (Address)

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

翻译成英语的地址。

转换后的地址无法作为 API 输入重复使用。该服务提供这些选项，以便用户使用其母语确认或拒绝对原始提供的地址进行验证。

如果地址的某个部分没有英语译文，该服务会使用使用拉丁字母的其他语言返回该部分。如需了解如何选择备用语言，请参阅此处。如果地址的某个部分没有任何使用拉丁字母的语言的翻译或转写，该服务会以与地址关联的本地语言返回该部分。

使用 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 字段未填充任何内容。

判定

地址验证结果和地理编码的简要概览。

JSON 表示法 
{
  "inputGranularity": enum (Granularity),
  "validationGranularity": enum (Granularity),
  "geocodeGranularity": enum (Granularity),
  "addressComplete": boolean,
  "hasUnconfirmedComponents": boolean,
  "hasInferredComponents": boolean,
  "hasReplacedComponents": boolean,
  "possibleNextAction": enum (PossibleNextAction),
  "hasSpellCorrectedComponents": boolean
}
字段
inputGranularity

enum (Granularity)

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

例如，如果输入的地址包含特定门牌号，则此处的 inputGranularity 将为 SUB_PREMISE。如果地址验证服务无法匹配数据库中的门牌号，或者门牌号无效，validationGranularity 可能为 PREMISE 或更粗略。
validationGranularity

enum (Granularity)

API 可以完全验证的经过处理的地址的精细程度。例如，validationGranularity 为 PREMISE 表示可以验证级别为 PREMISE 或更粗的所有地址组成部分。

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

enum (Granularity)

有关 geocode 精细度的相关信息。这可以理解为地理编码位置的精确程度。

这可能与上面的 validationGranularity 不同。例如，我们的数据库可能会记录某个门牌号的存在，但没有该门牌号在大型公寓楼中的确切位置。在这种情况下，validationGranularity 将为 SUB_PREMISE，但 geocodeGranularity 将为 PREMISE。
addressComplete

boolean

如果没有未解析的令牌、没有意外的地址组成部分或缺少地址组成部分，则系统会将经过处理的地址视为完整。如果未设置，表示值为 false。如需了解详情，请参阅 missingComponentTypes、unresolvedTokens 或 unexpected 字段。
hasUnconfirmedComponents

boolean

至少有一个地址组件无法分类或验证，详情请参阅 google.maps.addressvalidation.v1.Address.address_components。
hasInferredComponents

boolean

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

boolean

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

enum (PossibleNextAction)

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

提供 API 响应的解读摘要，旨在协助确定可能采取的后续措施。此字段派生自 API 响应中的其他字段，不应视为保证地址准确性或可送达性。如需了解详情，请参阅构建验证逻辑。
hasSpellCorrectedComponents

boolean

系统更正了至少一个地址组成部分的拼写，如需了解详情，请参阅 google.maps.addressvalidation.v1.Address.address_components。

粒度

地址或地理编码可能具有的各种精确度。当用于指示地址的精细程度时，这些值表示地址用于标识邮寄目的地的细致程度。例如，“123 Main Street, Redwood City, CA, 94061”这样的地址表示 PREMISE，而“Redwood City, CA, 94061”这样的地址表示 LOCALITY。不过，如果我们找不到 Redwood City 的“123 Main Street”的地理编码，则返回的地理编码可能为 LOCALITY 精确度，即使地址的精确度更高也是如此。

枚举
GRANULARITY_UNSPECIFIED 默认值。此值未使用。
SUB_PREMISE 建筑物级别以下的结果，例如公寓。
PREMISE 建筑级结果。
PREMISE_PROXIMITY 大致表示地址的建筑物级位置的地理编码。
BLOCK 地址或地理编码表示街区。仅在采用街区级地址的区域（例如日本）使用。
ROUTE 地理编码或地址的粒度为路线，例如街道、道路或高速公路。
OTHER 所有其他精确度，由于无法传送，因此会归为一类。

PossibleNextAction

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

根据 API 响应，可以执行的可能后续操作。

枚举
POSSIBLE_NEXT_ACTION_UNSPECIFIED 默认值。此值未使用。
FIX API 响应的一个或多个字段表明经过处理的地址可能存在问题，例如 verdict.validation_granularity 为 OTHER。提示客户修改地址有助于提高地址质量。
CONFIRM_ADD_SUBPREMISES API 响应表明经过处理的地址可能缺少子门牌。提示客户检查地址并考虑添加单元号有助于提高地址质量。经过处理的地址可能还存在其他小问题。注意：此枚举值仅适用于美国地址。
CONFIRM API 响应的一个或多个字段表明经过处理的地址可能存在一些小问题，例如 postalCode 地址组成部分为 replaced。提示客户检查地址有助于提高地址质量。
ACCEPT API 响应不包含可证明其他 PossibleNextAction 值之一的信号。您可以考虑使用经过处理的地址，而无需进一步提示客户，但这并不保证地址有效，并且地址可能仍包含更正内容。您有责任根据自己的风险评估确定是否以及如何向客户发出提示。

地址

经过处理后的地址的详细信息。后处理包括更正地址中拼写错误的部分、替换不正确的部分以及推断缺失的部分。

JSON 表示法 
{
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "addressComponents": [
    {
      object (AddressComponent)
    }
  ],
  "missingComponentTypes": [
    string
  ],
  "unconfirmedComponentTypes": [
    string
  ],
  "unresolvedTokens": [
    string
  ]
}
字段
formattedAddress

string

经过处理的地址，格式为单行地址，遵循地址所在区域的地址格式规则。

注意：此地址的格式可能与 postalAddress 字段中的地址格式不一致。例如，postalAddress 始终将国家/地区表示为 2 个字母的 regionCode，例如“US”或“NZ”。与之相反，此字段使用国家/地区名称的长形式，例如“美国”或“新西兰”。
postalAddress

object (PostalAddress)

经过处理后的地址，表示为邮政地址。
addressComponents[]

object (AddressComponent)

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

地址组成部分没有特定的排序方式。请勿对列表中地址组成部分的排序做出任何假设。
missingComponentTypes[]

string

应在格式正确的邮寄地址中存在但在输入中未找到且无法推断的组件类型。例如，如果输入值为“Boulder, Colorado, 80301, USA”，则 ['street_number', 'route'] 就是相应的地理编码。您可以在此处找到可能的类型列表。

注意：当您认为自己已提供缺少的组件时，可能会看到缺少组件类型。例如，如果输入的地址包含建筑物名称，但不包含门牌号，就可能会出现这种情况。在地址“渋谷区渋谷３丁目　 Shibuya Stream”中，“Shibuya Stream”建筑物名称的组成部分类型为 premise，但缺少门牌号，因此 missingComponentTypes 将包含 premise。
unconfirmedComponentTypes[]

string

addressComponents 中存在但无法确认是否正确的组件类型。此字段是为了方便起见而提供的：其内容相当于迭代 addressComponents 以查找 confirmationLevel 不为 CONFIRMED 或 inferred 标志未设置为 true 的所有组件的类型。您可以在此处找到可能的类型列表。
unresolvedTokens[]

string

输入中无法解析的任何令牌。这可能是因为输入内容未被识别为地址的有效部分。例如，对于“Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US”这样的输入，未解析的令牌可能如下所示：["Parcel", "0000123123", "&", "0000456456"]。

AddressComponent

表示地址组成部分，例如街道、城市或州。

JSON 表示法 
{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}
字段
componentName

object (ComponentName)

此组件的名称。
componentType

string

地址组成部分的类型。如需查看可能类型的列表，请参阅表 2：地点服务返回的其他类型。
confirmationLevel

enum (ConfirmationLevel)

表示我们对组件正确性的确信程度。
inferred

boolean

表示该组成部分并非输入内容的一部分，但我们根据地址位置推断出了该组成部分，并认为应提供该组成部分以便提供完整地址。
spellCorrected

boolean

表示更正了组件名称中的拼写错误。该 API 并不总会标记从一种拼写变体更改为另一种拼写变体，例如将“centre”更改为“center”。此外，它也不一定会标记常见的拼写错误，例如将“Amphitheater Pkwy”更改为“Amphitheatre Pkwy”。
replaced

boolean

表示组件的名称已被完全不同的名称替换，例如错误的邮政编码被替换为与地址相符的邮政编码。这不是外观上的更改，输入组件已更改为其他组件。
unexpected

boolean

表示给定地区的邮政地址中不应包含的地址组成部分。我们之所以保留该信息，是因为它是输入内容的一部分。

ComponentName

组件名称的封装容器。

JSON 表示法 
{
  "text": string,
  "languageCode": string
}
字段
text

string

名称文本。例如，街道名称为“第 5 大道”，门牌号为“1253”。
languageCode

string

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

ConfirmationLevel

确认级别的不同可能值。

枚举
CONFIRMATION_LEVEL_UNSPECIFIED 默认值。此值未使用。
CONFIRMED 我们能够验证此组件存在，并且在地址的其余部分中合理。
UNCONFIRMED_BUT_PLAUSIBLE 我们无法确认此组件，但它可能存在。例如，某条街道上的门牌号，其门牌号位于已知有效范围内，但具体门牌号未知。
UNCONFIRMED_AND_SUSPICIOUS 此组件未经确认，可能不正确。例如，与地址的其余部分不符的街区。

地理编码

包含与输入内容经过地理编码的地点相关的信息。

JSON 表示法 
{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}
字段
location

object (LatLng)

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

建议使用地点 ID，而不是使用地址、纬度/经度坐标或 Plus Code。在规划路线或计算驾车路线时使用坐标，始终会导致相应点被捕获到距离这些坐标最近的道路。此路线可能无法快速或安全地抵达目的地，也可能不在相应房源的入口附近。此外，对某个位置进行逆向地理编码时，无法保证返回的地址与原始地址一致。
plusCode

object (PlusCode)

与 location 对应的 Plus Code。
bounds

object (Viewport)

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

number

经过地理编码的地点的大小（以米为单位）。这是衡量经过地理编码的位置粗糙程度的另一种方法，但以实际大小（而非语义含义）衡量。
placeId

string

此输入地理编码的地点的 PlaceID。

如需详细了解地点 ID，请点击此处。
placeTypes[]

string

输入内容经过地理编码后对应的地点类型。例如，['locality', 'political']。您可以点击此处查看完整的类型列表。

LatLng

表示纬度/经度对的对象。该对象以一对双精度数表示，分别代表纬度度数和经度度数。除非另有说明，否则该对象必须符合 WGS84 标准。值必须介于标准化范围内。

JSON 表示法 
{
  "latitude": number,
  "longitude": number
}
字段
latitude

number

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

number

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

PlusCode

Plus Code（http://plus.codes）是一种位置参考，有两种格式：全局代码（定义 14 米 x 14 米 [1/8,000 度] 或更小的矩形）和复合代码（将前缀替换为参考位置）。

JSON 表示法 
{
  "globalCode": string,
  "compoundCode": string
}
字段
globalCode

string

地点的全局（完整）代码，例如“9FWM33GV+HQ”，表示 1/8, 000 度 x 1/8,000 度（约 14 米 x 14 米）的区域。
compoundCode

string

地点的混合代码，例如“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 (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
字段
low

object (LatLng)

必需。视口的最低点。
high

object (LatLng)

必需。视口的高点。

AddressMetadata

经过处理后的地址的元数据。无法保证为发送到 Address Validation API 的每个地址都完全填充 metadata。

JSON 表示法 
{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}
字段
business

boolean

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

boolean

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

boolean

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

UspsData

相应地址的 USPS 数据。我们无法保证为发送到 Address Validation API 的每个美国或美属波多黎各地址都填充完整的 uspsData。如果您将 uspsData 用作响应的主要部分，建议您在响应中集成备用地址字段。

JSON 表示法 
{
  "standardizedAddress": {
    object (UspsAddress)
  },
  "deliveryPointCode": string,
  "deliveryPointCheckDigit": string,
  "dpvConfirmation": string,
  "dpvFootnote": string,
  "dpvCmra": string,
  "dpvVacant": string,
  "dpvNoStat": string,
  "dpvNoStatReasonCode": integer,
  "dpvDrop": string,
  "dpvThrowback": string,
  "dpvNonDeliveryDays": string,
  "dpvNonDeliveryDaysValues": integer,
  "dpvNoSecureLocation": string,
  "dpvPbsa": string,
  "dpvDoorNotAccessible": string,
  "dpvEnhancedDeliveryCode": 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
}
字段
standardizedAddress

object (UspsAddress)

USPS 标准地址。
deliveryPointCode

string

2 位数投递点代码
deliveryPointCheckDigit

string

送货点校验码。对于机械扫描的邮件，此编号会添加到 delivery_point_barcode 的末尾。将 delivery_point_barcode、deliveryPointCheckDigit、邮政编码和邮政编码+4 的所有数字相加，所得数字应为 10 的倍数。
dpvConfirmation

string

DPV 确认的可能值。返回单个字符或不返回任何值。

  • N：主号码和所有辅助号码信息均未能通过 DPV 确认。
  • D：仅主号码的地址通过了 DPV 确认，次要号码信息缺失。
  • S：仅主号码的地址通过了 DPV 确认，次要号码信息存在但未确认。
  • Y：主要号码和所有辅助号码的地址已通过 DPV 确认。
  • 空：如果响应不包含 dpvConfirmation 值，则表示地址未提交以进行 DPV 确认。
dpvFootnote

string

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

  • AA：与邮政编码+4 文件匹配的输入地址
  • A1：输入的地址与邮政编码+4 文件不匹配
  • BB：与 DPV 匹配（所有组件）
  • CC：辅助号码不匹配，但不是必需的
  • C1：辅助号码不匹配，但必填
  • N1：高层建筑地址缺少副号
  • M1：缺少主号码
  • M3：主号码无效
  • P1：输入地址缺少 PO、RR 或 HC 信箱号
  • P3：输入的地址 PO、RR 或 HC 信箱号无效
  • F1：输入的地址与军事地址匹配
  • G1：输入的地址与通用送货地址匹配
  • U1：输入的地址与唯一的邮政编码匹配
  • PB：与 PBSA 记录匹配的输入地址
  • RR：包含 PMB 信息的 DPV 确认地址
  • R1：没有 PMB 信息的 DPV 确认地址
  • R7：运营商路线 R777 或 R779 记录
  • IA：已识别出已获知地址
  • TA：通过舍弃尾随字母匹配的主号码
dpvCmra

string

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

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

string

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

  • Y：地址空置
  • N：地址不空闲
dpvNoStat

string

这是无状态地址还是有效地址？无统计地址是指未持续有人居住或 USPS 不提供服务的地址。返回单个字符。

  • Y：地址处于非活动状态
  • N：地址处于有效状态
dpvNoStatReasonCode

integer

表示 NoStat 类型。以 int 的形式返回原因代码。

  • 1：IDA（内部投递地址）- 这些地址不会直接从 USPS 接收邮件，而是会投递到为其提供服务的投递地址。
  • 2：CDS - 尚未可配送的地址。例如，已确定地块和主编号，但尚无可供入住的结构的新分区。
  • 3：碰撞 - 实际上未通过 DPV 确认的地址。
  • 4：CMZ（学院、军事和其他类型）- USPS 已将邮政编码 + 4 个记录纳入数据中。
  • 5：常规 - 表示未送达的地址，这些地址不会计入可能送达的地址。
  • 6：必须提供辅助信息 - 地址需要辅助信息。
dpvDrop

string

此标志表示邮件会投递到某个地点的单个收件箱。返回单个字符。

  • Y：邮件会投递到相应地点的单个收件箱。
  • N：邮件未投递到相应地点的单个收件箱。
dpvThrowback

string

表示邮件未投递到相应街道地址。返回单个字符。

  • Y：邮件未投递到街道地址。
  • N：邮件会配送到街道地址。
dpvNonDeliveryDays

string

此标志表示邮件递送并非每周七天都进行。返回单个字符。

  • Y：邮件配送并非每周七天都进行。
  • N：未指明邮件配送不是每周七天都进行。
dpvNonDeliveryDaysValues

integer

用于标识未投放天数的整数。您可以使用位标志进行查询：0x40 - 星期日为非送货日；0x20 - 星期一为非送货日；0x10 - 星期二为非送货日；0x08 - 星期三为非送货日；0x04 - 星期四为非送货日；0x02 - 星期五为非送货日；0x01 - 星期六为非送货日
dpvNoSecureLocation

string

此标志表示可以进入门户，但由于安全问题，不会将包裹留在门口。返回单个字符。

  • Y：出于安全考虑，系统不会保留该文件包。
  • N：未指明软件包不会因安全问题而保留。
dpvPbsa

string

表示地址与 PBSA 记录匹配。返回单个字符。

  • Y：地址与 PBSA 记录匹配。
  • N：地址与 PBSA 记录不匹配。
dpvDoorNotAccessible

string

此标志表示 USPS 无法敲门递送邮件的地址。返回单个字符。

  • Y：无法进入门内。
  • N：未指明门无法进入。
dpvEnhancedDeliveryCode

string

表示该地址有多个有效的 DPV 返回代码。返回单个字符。

  • Y：主要号码和所有辅助号码的地址已通过 DPV 确认。
  • N：主号码和所有辅助号码信息均未能通过 DPV 确认。
  • S：仅主号码的地址通过了 DPV 验证，次要号码信息存在但未经验证，或者主号码的尾随字母被舍弃以进行 DPV 匹配，并且需要提供次要信息。
  • D：仅主号码的地址通过了 DPV 确认，次要号码信息缺失。
  • R：地址已确认，但分配给了虚构路线 R777 和 R779，并且未提供 USPS 配送服务。
carrierRoute

string

运输公司路线代码。一个由一个字母前缀和一个三位数路线标识符组成的四位字符代码。

前缀：

  • C：运营商路线（或城市路线）
  • R：乡村路线
  • H：高速公路合同路线
  • B：邮政信箱部分
  • G：一般配送部门
carrierRouteIndicator

string

运营商路线费率排序指标。
ewsNoMatch

boolean

送货地址可匹配，但 EWS 文件显示很快就会有完全匹配的地址。
postOfficeCity

string

主邮局所在的城市。
postOfficeState

string

主邮局状态。
abbreviatedCity

string

城市缩写。
fipsCountyCode

string

FIPS 县代码。
county

string

郡/县名称。
elotNumber

string

增强型航线 (eLOT) 编号。
elotFlag

string

eLOT 升序/降序标志 (A/D)。
poBoxOnlyPostalCode

boolean

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

string

PMB（私人邮箱）单元标识符。
pmbNumber

string

PMB（私人邮箱）编号；
addressRecordType

string

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

  • F：FIRM。这是与公司记录的匹配，这是地址可获得的最精确匹配级别。
  • G：一般配送。此地址与“General Delivery”（一般递送）记录匹配。
  • H：大楼 / 公寓。此值与建筑物或公寓记录匹配。
  • P：邮政信箱。此地址与邮政信箱相符。
  • R：乡村道路或高速公路合同：与乡村道路或高速公路合同记录匹配，这两者都可能具有关联的邮政信箱编号范围。
  • S：街道记录：与包含有效主号码范围的街道记录匹配。
defaultAddress

boolean

指示找到了默认地址，但存在更具体的地址。
errorMessage

string

USPS 数据检索错误消息。如果 USPS 检测到人为创建的地址，则会暂停处理，并填充此字段。

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

boolean

指示请求已通过 CASS 处理的指标。

UspsAddress

USPS 表示美国地址的格式。

JSON 表示法 
{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}
字段
firstAddressLine

string

地址的第一行。
firm

string

公司名称。
secondAddressLine

string

地址的第二行。
urbanization

string

波多黎各城市化区域名称。
cityStateZipAddressLine

string

城市 + 州/省级行政区 + 邮政编码。
city

string

城市名称。
state

string

由 2 个字母组成的州代码。
zipCode

string

邮政编码，例如 10009。
zipCodeExtension

string

4 位数的邮政编码附加信息，例如 5023。