Package google.maps.addressvalidation.v1

索引

• AddressValidation（接口）
• Address（消息）
• AddressComponent（消息）
• AddressComponent.ConfirmationLevel（枚举）
• AddressMetadata（消息）
• ComponentName（消息）
• Geocode（消息）
• LanguageOptions（消息）
• PlusCode（消息）
• ProvideValidationFeedbackRequest（消息）
• ProvideValidationFeedbackRequest.ValidationConclusion（枚举）
• ProvideValidationFeedbackResponse（消息）
• UspsAddress（消息）
• UspsData（消息）
• ValidateAddressRequest（消息）
• ValidateAddressResponse（消息）
• ValidationResult（消息）
• Verdict（消息）
• Verdict.Granularity（枚举）

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 名称文本。例如，“第五大道”表示街道名称，“1253”表示门牌号。
language_code	string BCP-47 语言代码。如果组件名称没有与语言（例如门牌号）相关联，系统不会显示此属性。

地理编码

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

字段
location	LatLng 输入内容的地理编码位置。 与使用地址、纬度/经度坐标或 Plus 代码相比，使用地点 ID 更好。在规划路线或计算行车路线时使用坐标，总会导致该点与最接近这些坐标的道路对应。道路不能快速或安全地到达目的地，并且不在房源入口附近。此外，当对某个位置进行反向地理编码时，无法保证返回的地址与原始地址匹配。
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 代码 (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.验证 AddressRequest.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 双字母州代码。
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_digital、postal code 和 ZIP+4 的所有数字相加，将得到一个可被 10 整除的数字。
dpv_confirmation	string DPV 确认的可能值。返回单个字符或不返回任何值。 N：未能确认主要号码和任何辅助号码信息。 D：已仅为主号码确认地址，而辅助号码信息缺失。 S：已仅针对主号码确认地址，且辅助号码信息存在但未确认。 Y：已通过 DPV 确认了主要号码和所有辅助号码的地址。 Empty：如果响应不包含 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 类型。返回 int 类型的原因代码。 1：IDA（内部配送地址）- 不直接从 USPS 接收邮件，但会配送到为其提供服务的配送地址的地址。 2：CDS - 尚不能配送的地址。例如，一个新细分，其中地块和一级编号已确定，但入住人数还没有结构。 3：冲突 - 未实际 DPV 确认的地址。 4：CMZ（大学、军事和其他类型）- 数据中加入了 USPS 的 4 条记录。 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 – 星期五是星期六不送货的日 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：未能确认主要号码和任何辅助号码信息。 S：地址已针对主号码进行 DPV 确认，而辅助号码信息因未确认而出现，或者主号码的单个尾随 alpha 被丢弃，以使 DPV 匹配并需要辅助信息。 D：已仅为主号码确认地址，而辅助号码信息缺失。 R：已确认地址但已分配给幻影 R777 和 R779 路线，且未提供 USPS 送货服务。
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)。
lacs_link_return_code	string LACSLink 返回代码。
lacs_link_indicator	string LACSLink 指示器。
po_box_only_postal_code	bool 仅限邮政信箱的邮政编码。
suitelink_footnote	string 将街道或高层记录与套房信息进行匹配的脚注。如果找到匹配的商家名称，则返回辅助编号。 A：SuiteLink 记录匹配，商家地址已改进。 00：不匹配，商家地址未改进。
pmb_designator	string PMB（私人邮箱）单元指示符。
pmb_number	string PMB（私人邮箱）号码；
address_record_type	string 与输入地址匹配的地址记录的类型。 F：FIRM。这是与公司记录的匹配，公司记录是对地址而言最精确的匹配级别。 G：一般交付。这与常规递送记录匹配。 H：BUILDING / APARTMENT（住宅）。这是与建筑物或公寓记录匹配的结果。 P：邮政信箱这与邮政信箱相匹配。 R：RURAL ROUTE 或 HIGHWAY CONTRACT：这与乡村路线或公路合同记录匹配，这两者可能有关联的方框编号范围。 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”，或者提供 address 的 google.type.PostalAddress.administrative_area 作为“波多黎各”（不区分大小写）或“PR”。 建议使用组件化的 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 输入地址的粒度。这是解析输入地址的结果，不会提供任何验证信号。如需了解验证信号，请参阅下面的 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 Main Street”的地理编码，那么即使地址更加细化，返回的地理编码也可能采用 LOCALITY 的粒度。

枚举
GRANULARITY_UNSPECIFIED	默认值。此值未使用。
SUB_PREMISE	楼下级别的搜索结果，如公寓。
PREMISE	建筑物级结果。
PREMISE_PROXIMITY	大致表示地址的建筑物级位置的地理编码。
BLOCK	地址或地理编码表示街区。仅在具有块级寻址的区域使用，例如日本。
ROUTE	地理编码或地址要精确到路线，例如街道、道路或公路。
OTHER	所有其他粒度，因无法投放而分桶在一起。