Package google.maps.addressvalidation.v1

索引

AddressValidation

用于验证地址的服务。

ProvideValidationFeedback

rpc ProvideValidationFeedback(ProvideValidationFeedbackRequest) returns (ProvideValidationFeedbackResponse)

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

rpc ValidateAddress(ValidateAddressRequest) returns (ValidateAddressResponse)

验证地址。

地址

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

字段
formatted_address

string

经过后处理的地址，按照地址所在地区的地址格式规则，采用单行地址格式。
postal_address

PostalAddress

以邮政地址表示的经过后处理的地址。
address_components[]

AddressComponent

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

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

string

某些组件属于以下类型：应该出现在格式正确的邮寄地址中，但在输入内容中找不到，且无法推断出的组件类型。formatted_address、postal_address 或 address_components 中不存在此类型的组件。例如，对于“Boulder, Colorado, 80301, USA”这样的输入，可以使用 ['street_number', 'route']。请点击此处查看可能的类型列表。
unconfirmed_component_types[]

string

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

string

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

AddressComponent

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

字段
component_name

ComponentName

此组件的名称。
component_type

string

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

ConfirmationLevel

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

bool

表示该组成部分不是输入内容的一部分，但我们根据地址位置推断出该组成部分，并认为应当针对完整地址提供该组成部分。
spell_corrected

bool

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

bool

表示组件名称已替换为完全不同的名称，例如，将错误的邮政编码替换为地址正确的邮政编码。这并不是一个界面外观上的变化，已对输入组件进行了更改。
unexpected

bool

表示指定地区的邮政地址中不应存在的地址组成部分。我们之所以将其保留下来，只是因为它是输入内容的一部分。

ConfirmationLevel

确认级别的不同可能值。

枚举
CONFIRMATION_LEVEL_UNSPECIFIED 默认值。此值未使用。
CONFIRMED 我们能够验证该组成部分是否存在，以及在地址的其余部分是否合理。
UNCONFIRMED_BUT_PLAUSIBLE 此组成部分无法确认，但确实存在。例如，某个街道上未知的有效门牌号。
UNCONFIRMED_AND_SUSPICIOUS 此组件未经确认，很可能有误。例如，某个社区与地址的其他部分不符。

AddressMetadata

地址的元数据。对于发送到 Address Validation API 的每个地址，系统不一定会完整填充 metadata。

字段
business

bool

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

bool

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

bool

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

ComponentName

组件名称的封装容器。

字段
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']。点击此处可查看类型的完整列表。

LanguageOptions

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

启用 Address Validation API，以在响应中包含其他信息。

字段
return_english_latin_address

bool

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

PlusCode

Plus Code (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, Norway”，其中包含全局代码的后缀，并将前缀替换为参考实体的格式化名称。

ProvideValidationFeedbackRequest

发送验证反馈的请求。

字段
conclusion

ValidationConclusion

必需。一系列验证尝试的结果。

如果此字段设置为 VALIDATION_CONCLUSION_UNSPECIFIED，则会返回 INVALID_ARGUMENT 错误。
response_id

string

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

ValidationConclusion

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

枚举
VALIDATION_CONCLUSION_UNSPECIFIED 未使用此值。如果 ProvideValidationFeedbackRequest.conclusion 字段设置为 VALIDATION_CONCLUSION_UNSPECIFIED，则会返回 INVALID_ARGUMENT 错误。
VALIDATED_VERSION_USED 交易使用的是 Address Validation API 返回的地址版本。
USER_VERSION_USED 交易使用了用户提供的地址版本
UNVALIDATED_VERSION_USED 交易使用了上次验证尝试之后输入但未重新验证的地址版本。
UNUSED 交易被放弃，地址将被取消。

ProvideValidationFeedbackResponse

此类型没有字段。

对验证反馈的响应。

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

UspsAddress

美国地址的 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 的每个美国或公共地址，我们不保证会完整填充 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 确认的可能值。返回单个字符或不返回任何值。

  • N：DPV 无法确认主要号码和任何次要号码信息。
  • D：只有主要号码的 DPV 确认了地址，但次要号码信息缺失。
  • S：只有主要号码的 DPV 确认了地址，而次要号码信息存在但未确认。
  • Y：主要号码和所有次要号码已通过 DPV 确认。
  • 空：如果响应不包含 dpv_confirmation 值，则表示未提交地址以供 DPV 确认。
dpv_footnote

string

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

  • AA：与 ZIP+4 文件匹配的输入地址
  • A1：输入地址与 ZIP+4 文件不匹配
  • BB：与 DPV 匹配（所有组件）
  • CC：辅助号码不匹配，不需要提供
  • C1：次要号码不匹配，但必须提供
  • N1：高层地址缺少次要号码
  • M1：缺少主号码
  • M3：主电话号码无效
  • P1：输入地址的采购订单、RR 或 HC 邮箱编号缺失
  • P3：输入地址的采购订单、RR 或 HC 邮箱编号无效
  • F1：与军事地址匹配的输入地址
  • G1：与常规送货地址匹配的输入地址
  • U1：与唯一邮政编码匹配的输入地址
  • PB：输入地址与 PBSA 记录匹配
  • RR：DPV 已确认地址，其中包含 PMB 信息
  • R1：DPV 已确认地址，但不包含 PMB 信息
  • R7：运营商 Route R777 或 R779 记录
  • IA：已找到知情地址
  • TA：通过丢弃尾随 alpha 值匹配的主数字
dpv_cmra

string

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

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

string

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

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

string

此地址是没有统计信息的地址还是有效地址？没有统计地址是指未被持续使用的地址或 USPS 不提供服务的地址。返回单个字符。

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

int32

表示 NoStat 类型。以整数形式返回原因代码。

  • 1：IDA（内部投递地址）- 不直接从 USPS 接收邮件，但递送到为其提供服务的投递地址的地址。
  • 2：CDS - 尚无法递送的地址。例如，某个新细分已经确定了地段和主要编号，但尚无入座率数据结构。
  • 3：冲突 - 未实际 DPV 确认的地址。
  • 4：CMZ（大学、军事及其他类型）- ZIP + 4 条记录 USPS 已纳入数据。
  • 5：普通 - 表示未收到包裹地址，且这些地址不算作可能送达的地址。
  • 6：次要必填 - 该地址需要次要信息。
dpv_drop

string

标记表示邮件递送到站点中的单个可接收设备。返回单个字符。

  • Y：邮件递送到某站点的单个可接收设备。
  • N：邮件未递送到某站点的单个可接收设备。
dpv_throwback

string

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

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

string

标记表示并非一周的每一天都执行邮件递送。返回单个字符。

  • Y：并非一周的每一天都执行邮件递送。
  • N：没有表明邮件并非一周的每一天都递送。
dpv_non_delivery_days_values

int32

用于标识未投放日期的整数。可以使用位标志询问该日期：0x40 – 星期日是无法送达的日 0x20 – 星期一是无法送达的日 0x10 – 星期二是无法送达的日 0x08 – 星期三是无法送达的日 0x04 – 星期四是无法送达的日 0x02 – 星期五是无法送达的日
dpv_no_secure_location

string

该标记表示门可以进入，但出于安全考虑，包裹不会寄出。返回单个字符。

  • Y：出于安全考虑，系统无法移除此包裹。
  • N：没有指示由于安全原因，相应软件包无法退出。
dpv_pbsa

string

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

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

string

标记指明了 USPS 无法敲门递送邮件的地址。返回单个字符。

  • Y：无法打开门。
  • N：没有指示无法进入车门。
dpv_enhanced_delivery_code

string

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

  • Y：主要号码和所有次要号码已通过 DPV 确认。
  • N：DPV 无法确认主要号码和任何次要号码信息。
  • S：地址仅通过主号码确认，DPV 已确认，辅助号码信息显示但未经确认，或主号码上有一个尾随字母丢失，以匹配 DPV 并要求提供辅助信息。
  • D：只有主要号码的 DPV 确认了地址，但次要号码信息缺失。
  • R：地址已确认，但未分配给幻影航线 R777 和 R779 以及 USPS 配送。
carrier_route

string

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

前缀：

  • 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：POST OFFICE BOX。这与邮政信箱匹配。
  • R：“RURAL ROUTE”或“HIGHWAY CONTRACT”：与“农村路线”或“公路合同”记录匹配，两者都可能具有关联的 Box Number 范围。
  • S：STREET RECORD：这与包含有效主要号码范围的街道记录匹配。
default_address

bool

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

string

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

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

bool

表明请求已由 CASS 处理的指示符。

ValidateAddressRequest

验证地址的请求。

字段
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 的波多黎各地址请求，必须提供 address 的 google.type.PostalAddress.region_code 作为“PR”，或者以“Puerto Rico”（不区分大小写）或“PR”的形式提供 address 的 google.type.PostalAddress.administrative_area。

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

LanguageOptions

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

启用 Address Validation API，以在响应中包含其他信息。
session_token

string

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

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

注意：地址验证功能只能在使用 Autocomplete（新）API（而非 Autocomplete API）的会话中使用。如需了解详情，请参阅 https://developers.google.com/maps/documentation/places/web-service/session-pricing。

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 地区提供。
english_latin_address

Address

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

翻译成英文的地址。

翻译后的地址不可重复使用作为 API 输入。服务提供这些信息，以便用户能够使用母语来确认或拒绝对最初提供的地址的验证。

如果地址的一部分没有英语翻译，该服务会以使用拉丁字母的备用语言返回该部分。请参阅此处，了解如何选择备用语言。如果地址的这部分内容没有任何使用拉丁字母的语言的翻译或音译，该服务会以与该地址关联的当地语言返回这部分。

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

注意：english_latin_address 中的 google.maps.addressvalidation.v1.Address.unconfirmed_component_types 字段和 english_latin_address.address_components 中的 google.maps.addressvalidation.v1.AddressComponent.confirmation_level 字段未填充。

判定

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

字段
input_granularity

Granularity

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

例如，如果输入地址包含具体的公寓号，则此处的 input_granularity 将为 SUB_PREMISE。如果数据库中的公寓号与数据库中的公寓号不匹配，或者公寓号无效，则 validation_granularity 的值可能为 PREMISE 或以下。
validation_granularity

Granularity

API 能够对地址进行全面validate的粒度级别。例如，如果 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

如果没有任何未解析的令牌、意外或缺失的地址组成部分，则相应地址会被视为完整地址。如果未设置，则表示值为 false。如需了解详情，请参阅 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 号”的地理编码，返回的地理编码可能含有 LOCALITY 粒度（即使相应地址更为细化）。

枚举
GRANULARITY_UNSPECIFIED 默认值。此值未使用。
SUB_PREMISE 楼下楼层结果，例如公寓。
PREMISE 建筑物级结果。
PREMISE_PROXIMITY 近似地表示地址的建筑物级位置的地理编码。
BLOCK 地址或地理编码表示一个街区。仅在具有块级寻址的区域（例如日本）中使用。
ROUTE 地理编码或地址用于细化路线，例如街道、道路或公路。
OTHER 所有其他粒度（由于无法交付而分桶在一起）。