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 字段中的地址格式不一致。例如，postal_address 始终使用 2 个字母 region_code 表示国家/地区，如“US”或“NZ”。与之相反，此字段使用国家/地区名称的长形式，例如“美国”或“新西兰”。
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 输入中任何无法解析的令牌。这可能是因为输入内容未被识别为地址的有效部分。例如，对于“Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US”这样的输入，未解析的令牌可能如下所示：["Parcel", "0000123123", "&", "0000456456"]。

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 Code。在规划路线或计算驾车路线时使用坐标，始终会导致相应点被拉伸到距离这些坐标最近的道路。此道路可能不是快速或安全地通向目的地的道路，也可能不靠近物业的入口。此外，对某个位置进行逆向地理编码时，无法保证返回的地址与原始地址一致。
plus_code	PlusCode 与 location 对应的 Plus Code。
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）是一种位置参考，有两种格式：全局代码（定义 14 米 x 14 米 [1/8,000 度] 或更小的矩形）和复合代码（将前缀替换为参考位置）。

字段
global_code	string 地点的全局（完整）代码，例如“9FWM33GV+HQ”，表示 1/8,000 度 x 1/8,000 度（约 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.ValidateAddressRequest.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：输入地址缺少 PO、RR 或 HC 信箱号 P3：输入的地址邮政信箱、RR 信箱或 HC 信箱编号无效 F1：与军事地址匹配的输入地址 G1：输入的地址与通用送货地址匹配 U1：输入的地址与唯一的邮政编码匹配 PB：输入地址与 PBSA 记录匹配 RR：包含 PMB 信息的 DPV 确认地址 R1：没有 PMB 信息的 DPV 确认地址 R7：运营商路线 R777 或 R779 记录 IA：已找到知情地址 TA：通过舍弃尾随字母匹配的主号码
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 - 星期五为非送货日；0x01 - 星期六为非送货日
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 运输公司路线代码。一个由一个字母前缀和一个三位数路线标识符组成的四位字符代码。 前缀： 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：一般传送。此地址与“General Delivery”（一般递送）记录匹配。 H：大楼/公寓。此值与建筑物或公寓记录匹配。 P：邮政信箱。此地址与邮政信箱相符。 R：“RURAL ROUTE”或“HIGHWAY CONTRACT”：与“农村路线”或“公路合同”记录匹配，两者都可能具有关联的 Box Number 范围。 S：街道记录：与包含有效主号码范围的街道记录匹配。
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 参数或重复使用会话令牌，系统会按未提供会话令牌的情况为会话计费（每个请求均单独结算）。 注意：Address Validation 只能在使用 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 可以完全验证地址的精细级别。例如，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。不过，如果我们找不到 Redwood City 的“123 Main Street”的地理编码，则返回的地理编码可能为 LOCALITY 精确度，即使地址的精确度更高也是如此。

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