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 会忽略 recipientsorganization 中的值。这些字段中的任何值都将被舍弃,并且不会返回。请勿对其进行设置。

previousResponseId

string

对于第一个地址验证请求,此字段必须为空。如果需要更多请求来完全验证单个地址(例如,如果用户在初始验证后进行的更改需要重新验证),则每个后续请求都必须使用验证序列中第一个响应中的 responseId 填充此字段。

enableUspsCass

boolean

启用 USPS CASS 兼容模式。这只会影响 google.maps.addressvalidation.v1.ValidationResultgoogle.maps.addressvalidation.v1.ValidationResult.usps_data 字段。注意:对于针对波多黎各的地址启用 USPS CASS 的请求,必须提供 addressgoogle.type.PostalAddress.region_code 作为“PR”,或者必须提供 addressgoogle.type.PostalAddress.administrative_area 作为“波多黎各”(不区分大小写)或“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 参数,或重复使用会话令牌,系统会按未提供会话令牌的情况为会话收费(每个请求均单独计费)。

注意:地址验证功能只能在使用 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 或者其无法很好地对应这个结构的区域,应将 locality 留空并使用 address_lines。

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 提供的额外可递送性标志。仅在 USPR 地区提供。

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
}
字段
inputGranularity

enum (Granularity)

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

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

validationGranularity

enum (Granularity)

API 能够对地址进行全面验证的粒度级别。例如,如果 validationGranularityPREMISE,则表示可以验证粗略 PREMISE 级别或更高级别的所有地址组成部分。

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

geocodeGranularity

enum (Granularity)

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

此值偶尔可能与上面的 validationGranularity 不同。例如,我们的数据库可能记录了某个公寓号的存在,但没有某个大型公寓综合体内该公寓的精确位置。在这种情况下,validationGranularity 将为 SUB_PREMISE,但 geocodeGranularity 将为 PREMISE

addressComplete

boolean

如果没有任何未解析的令牌、意外或缺失的地址组成部分,则相应地址会被视为完整地址。如果未设置,则表示值为 false。如需了解详情,请参阅 missingComponentTypesunresolvedTokensunexpected 字段。

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

粒度

地址或地理编码可以具有的各种精细度。当用于表示地址的粒度时,这些值用来表示地址标识邮寄目的地的精细程度。例如,诸如“123 Main Street, Redwood City, CA, 94061”之类的地址。用于标识 PREMISE,而诸如“Redwood City, CA, 94061”之类的内容用于标识 LOCALITY。但是,如果我们找不到“主街 123 号”的地理编码,在 Redwood City,返回的地理编码可能是 LOCALITY 粒度,即使地址更精确。

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

地址

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

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

string

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

postalAddress

object (PostalAddress)

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

addressComponents[]

object (AddressComponent)

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

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

missingComponentTypes[]

string

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

unconfirmedComponentTypes[]

string

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

unresolvedTokens[]

string

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

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

名称文本。例如:"第五大道"输入街道名称,或输入“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 代码。在确定路线或计算行车路线时使用坐标值,总会让相应点与最接近这些坐标的道路对应起来。此道路可能既不能快速或安全地通向目的地,也可能不靠近物业的入口。此外,对某个位置进行反向地理编码时,无法保证返回的地址与原始地址一致。

plusCode

object (PlusCode)

location 对应的 Plus 代码。

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) 是采用两种格式的位置引用:定义 14mx14 米(1/8000 度)或更小矩形的全局代码,以及将前缀替换为引用位置的复合代码。

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

string

地点的全局(完整)代码,例如“9FWM33GV+HQ”,表示 1/8000 x 1/8000 度区域(约 14 x 14 米)。

compoundCode

string

地方的复合代码,例如“33GV+HQ, Ramberg, Norway”,其中包含全局代码的后缀,并将前缀替换为参考实体的格式化名称。

视口

经纬度视口,表示为两个对角线相对的 lowhigh 点。视口被视为封闭区域,即包含其边界。纬度边界必须介于 -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,纬度范围为空。

lowhigh 都必须填充,并且表示的框不得为空(如上述定义所指定)。视口为空会导致错误。

例如,以下视口将纽约市完全包围:

{ "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、邮政编码和 ZIP+4 的所有数字相加,得到一个可被 10 整除的数字。

dpvConfirmation

string

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

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

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 值匹配的主数字
dpvCmra

string

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

  • Y:地址属于 CMRA
  • N:地址不是 CMRA
dpvVacant

string

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

  • Y:地址是空的
  • N:地址不是空的
dpvNoStat

string

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

  • Y:地址无效
  • N:地址有效
dpvNoStatReasonCode

integer

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

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

string

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

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

string

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

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

string

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

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

integer

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

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

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

前缀:

  • 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:一般传送。这与常规递送记录匹配。
  • H:建筑物 / 公寓。这与“建筑物或公寓”记录匹配。
  • P:POST OFFICE BOX。这与邮政信箱匹配。
  • R:“RURAL ROUTE”或“HIGHWAY CONTRACT”:与“农村路线”或“公路合同”记录匹配,两者都可能具有关联的 Box Number 范围。
  • S:STREET RECORD:这与包含有效主要号码范围的街道记录匹配。
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。