Package google.maps.addressvalidation.v1

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

索引

地址验证

用于验证地址的服务。

提供验证反馈

rpc ProvideValidationFeedback(ProvideValidationFeedbackRequest) returns (ProvideValidationFeedbackResponse)

对验证尝试顺序结果的反馈。这应该是针对同一地址的一系列验证调用之后的最后调用，并且应在交易完成后调用。只应针对完整验证地址所需的 ValidateAddress 请求序列，仅发送一次此地址。
验证地址

rpc ValidateAddress(ValidateAddressRequest) returns (ValidateAddressResponse)

验证地址。

Address

从输入中解析的地址的详细信息。

字段
formatted_address

string

更正后的地址，格式采用单行地址格式，遵循地址所在区域的地址格式设置规则。
postal_address

PostalAddress

以邮政地址表示的经过验证的地址。
address_components[]

AddressComponent

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

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

string

应出现在格式正确的邮寄地址中，但其在输入内容中找不到且无法推断的组件类型。此类组件不在 formatted_address、postal_address 或 address_components 中。例如，['street_number', 'route'] 表示输入，如“Boulder, Colorado, 80301, USA”。您可以点击此处查看可能的类型列表。
unconfirmed_component_types[]

string

address_components 中存在但无法确定正确的组件类型。为方便起见，提供此字段：其内容等同于迭代 address_components，以查找 confirmation_level 并非 CONFIRMED 或 inferred 标志未设置为 true 的所有组件的类型。您可以点击此处查看可能的类型列表。
unresolved_tokens[]

string

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

地址组成部分

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

字段
component_name

ComponentName

此组件的名称。
component_type

string

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

ConfirmationLevel

表示我们确信组件正确无误的程度。
inferred

bool

表明该组成部分不属于输入内容，但我们会根据地址位置推断出该组成部分，因此我们认为应在完整地址中提供该组成部分。
spell_corrected

bool

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

bool

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

bool

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

确认级别

确认级别的不同可能值。

枚举
CONFIRMATION_LEVEL_UNSPECIFIED 默认值。此值未使用。
CONFIRMED 我们验证此组件是否存在，在地址的其余部分可以正常使用。
UNCONFIRMED_BUT_PLAUSIBLE 此组件无法确认，但可能确实存在。例如，街道上的电话号码是指已知有效门牌号范围内的街道号码。
UNCONFIRMED_AND_SUSPICIOUS 此组件未经确认，很可能是错误的。例如，某地区不符合地址的其余部分。

地址元数据

地址的元数据。对于发送到 Address Validation API 的每个地址，不能保证 metadata 完全填充。

字段
business

bool

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

bool

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

bool

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

组件名称

组件名称的封装容器。

字段
text

string

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

string

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

地理编码

包含有关输入内容的地理编码地点的信息。

字段
location

LatLng

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

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

PlusCode

对应于 location 的 Plus 代码。
bounds

Viewport

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

float

经过地理编码的地点的大小（以米为单位）。这是地理编码位置粗略的另一种衡量方式，但衡量的是物理大小而不是语义含义。
place_id

string

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

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

string

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

PlusCode

Plus 代码 (http://plus.codes) 是采用两种格式的地理位置引用：定义 14mx14m（1/8000 度）或更小矩形的全局代码，以及复合代码，将前缀替换为参考位置。

字段
global_code

string

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

string

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

ProvideValidationFeedback 请求

用于发送验证反馈的请求。

字段
conclusion

ValidationConclusion

必需。验证尝试序列的结果。

如果此字段设为 VALIDATION_CONCLUSION_UNSPECIFIED，系统将会返回 INVALID_ARGUMENT 错误。
response_id

string

必需。此反馈所针对的回复的 ID。这应该是一系列地址验证尝试中的第一个响应的 [response_id][google.maps.addressvalidation.v1.ValidateAddressRequest.response_id]。

验证总结

验证地址所需的一系列地址验证请求可能的最终结果。

枚举
VALIDATION_CONCLUSION_UNSPECIFIED 此值未使用。如果 ProvideValidationFeedbackRequest.conclusion 字段设置为 VALIDATION_CONCLUSION_UNSPECIFIED，系统将返回 INVALID_ARGUMENT 错误。
VALIDATED_VERSION_USED 该交易使用了 Address Validation API 返回的地址版本。
USER_VERSION_USED 交易所用的是用户提供的地址的版本
UNVALIDATED_VERSION_USED 系统针对相应交易使用了在上次验证尝试后输入但未重新验证的地址版本。
UNUSED 此交易已放弃，且未使用地址。

提供验证反馈响应

验证反馈的响应。

如果成功发送反馈，则响应为空。

UspsAddress

USPS 的 USPS 表示法。

字段
first_address_line

string

第一个地址行。
firm

string

公司名称。
second_address_line

string

第二行地址。
urbanization

string

波多黎各城市名称。
city_state_zip_address_line

string

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

string

城市名称。
state

string

由 2 个字母组成的状态代码。
zip_code

string

邮政编码，例如 10009。
zip_code_extension

string

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

uspsData

地址的 USPS 数据。对于发送到 Address Validation API 的每个美国或 PR 地址，不能保证 uspsData 会完全填充。如果您将响应中的 uspsData 用作主要部分，建议您将备用地址字段集成到响应中。

字段
standardized_address

UspsAddress

USPS 标准化地址。
delivery_point_code

string

2 位数送货代码
delivery_point_check_digit

string

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

string

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

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

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 记录
dpv_cmra

string

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

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

string

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

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

string

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

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

string

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

前缀：

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

string

运营商路由速率排序指示器。
ews_no_match

bool

送货地址可以匹配，但 EWS 文件会指明即将提供完全匹配的结果。
post_office_city

string

主要邮局所在城市。
post_office_state

string

主要邮局状态。
abbreviated_city

string

简写城市。
fips_county_code

string

FIPS 国家/地区代码。
county

string

郡/县名称。
elot_number

string

增强型旅游线路 (eLOT) 号码。
elot_flag

string

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

bool

仅邮政信箱邮政编码。
pmb_designator

string

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

string

PMB（私人邮箱）编号；
address_record_type

string

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

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

bool

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

string

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

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

bool

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

验证地址请求

用于验证地址的请求。

字段
address

PostalAddress

必需。正在验证的地址。无格式地址应通过 address_lines 提交。

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

如需了解支持的地区，请参阅常见问题解答。

输入地址中的 language_code 值预留供将来使用，并在今天忽略。系统会根据指定地址的首选语言（由系统标识）填充经过验证的地址结果。

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

string

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

bool

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

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

ValidateAddressResponse

对地址验证请求的响应。

字段
result

ValidationResult

地址验证的结果。
response_id

string

用于标识此响应的 UUID。如果需要重新验证地址，则此 UUID 必须随新请求一起提供。

ValidationResult

验证地址的结果。

字段
verdict

Verdict

总体认定结果标记
address

Address

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

Geocode

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

AddressMetadata

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

UspsData

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

判定

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

字段
input_granularity

Granularity

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

例如，如果输入地址包含特定的公寓编号，则此处的 input_granularity 将是 SUB_PREMISE。如果我们在数据库中找不到公寓编号，或者公寓编号无效，则validation_granularity可能为 PREMISE 或更低。
validation_granularity

Granularity

API 可完整验证地址的粒度级别。例如，validation_granularity 为 PREMISE 表示可以验证级别不低于 PREMISE 的所有地址组成部分。

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

Granularity

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

这有时可能与上述 validation_granularity 不同。例如，我们的数据库可能会记录公寓号的存在，但没有在大公寓楼中拥有公寓的确切位置。在这种情况下，validation_granularity 将为 SUB_PREMISE，但 geocode_granularity 将为 PREMISE。
address_complete

bool

如果没有未解析的令牌，没有意外的或缺少的地址组成部分，地址会被视为完整。如需了解详情，请参阅 missing_component_types、unresolved_tokens 或 unexpected 字段。
has_unconfirmed_components

bool

至少有一个地址组成部分无法分类或验证。如需了解详情，请参阅 google.maps.addressvalidation.v1.Address.address_components。
has_inferred_components

bool

至少推断出一个地址组成部分（添加），但输入中不包含该信息。如需了解详情，请参阅 google.maps.addressvalidation.v1.Address.address_components。
has_replaced_components

bool

至少有一个地址组件已被替换，请参阅 google.maps.addressvalidation.v1.Address.address_components 了解详情。

细化程度

地址或地理编码可以使用的各种粒度。这些值用于表示某个地址的粒度，而地址则是指地址标识出邮件目的地的粒度。例如，“123 Main Street, Redwood City, CA, 94061”这样的地址用于标识 PREMISE，而“Redwood City, CA, 94061”之类的地址用于标识 LOCALITY。但是，如果我们在雷德伍德城找不到“123 Main Street”的地理编码，返回的地址可能已经是 LOCALITY 的粒度，即使地址已经更精细了。

枚举
GRANULARITY_UNSPECIFIED 默认值。此值未使用。
SUB_PREMISE 楼下楼层的成果，例如公寓。
PREMISE 建筑物级结果。
PREMISE_PROXIMITY 一个地理编码，该地址应非常接近该地址的建筑物级别。仅用于地理编码，不用于地址。
BLOCK 地址或地理编码表示块。仅在具有块级地址的区域使用，如日本。
ROUTE 地理编码或地址是经过精细化处理的路线，例如街道、道路或高速公路。
OTHER 所有其他粒度，因为它们无法传递，因此它们会分桶。