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)

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

例如,如果输入地址包含具体的公寓编号,则此处的 inputGranularity 将为 SUB_PREMISE。如果我们无法匹配数据库中的公寓号码或者公寓号码无效,那么 validationGranularity 很可能为 PREMISE 或更低。

validationGranularity

enum (Granularity)

API 可以将地址完全validate到的粒度级别。例如,如果 validationGranularityPREMISE,则表示可以验证 PREMISE 级别或更粗略级别的所有地址组成部分。

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

geocodeGranularity

enum (Granularity)

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

此值偶尔可能与上面的 validationGranularity 不同。例如,我们的数据库可能会记录有公寓编号,但是在大型公寓大楼内并不知道该公寓的精确位置。在这种情况下,validationGranularitySUB_PREMISE,但 geocodeGranularityPREMISE

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 Main Street”的地理编码,那么即使地址更加细化,返回的地理编码也可能采用 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)

输入内容的地理编码位置。

与使用地址、纬度/经度坐标或 Plus 代码相比,使用地点 ID 更好。在规划路线或计算行车路线时使用坐标,总会导致该点与最接近这些坐标的道路对应。道路不能快速或安全地到达目的地,并且不在房源入口附近。此外,当对某个位置进行反向地理编码时,无法保证返回的地址与原始地址匹配。

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 代码 (http://plus.codes) 是两种格式的位置参考:定义一个 14mx14m(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”)包含全局代码的后缀,并将前缀替换为参考实体的格式化名称。

视口

经纬度视口,表示为两个对角线的 low 点和 high 点。视口会被视为封闭区域,即包含边界。纬度范围必须在 -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:未能确认主要号码和任何辅助号码信息。
  • D:已仅为主号码确认地址,而辅助号码信息缺失。
  • S:已仅针对主号码确认地址,且辅助号码信息存在但未确认。
  • Y:已通过 DPV 确认了主要号码和所有辅助号码的地址。
  • Empty:如果响应不包含 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 类型。返回 int 类型的原因代码。

  • 1:IDA(内部配送地址)- 不直接从 USPS 接收邮件,但会配送到为其提供服务的配送地址的地址。
  • 2:CDS - 尚不能配送的地址。例如,一个新细分,其中地块和一级编号已确定,但入住人数还没有结构。
  • 3:冲突 - 未实际 DPV 确认的地址。
  • 4:CMZ(大学、军事和其他类型)- 数据中加入了 USPS 的 4 条记录。
  • 5:常规 - 表示未收到包裹的地址,且这些地址不计为可能的递送。
  • 6:必须提供次要信息 - 地址必须提供次要信息。
dpvDrop

string

该标记表示邮件已递送至某个网站的单个可接收设备。返回单个字符。

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

string

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

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

string

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

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

integer

用于标识未投放天数的整数。可以使用位标志进行查询:0x40 – 星期日是不送货的日 0x20 – 星期一是不送货的日 0x10 – 星期二是不送货的日 0x08 – 星期三是不送货的日 0x04 – 星期四是不送货的日 0x02 – 星期五是星期六不送货的日 0x02

dpvNoSecureLocation

string

旗帜表示门可以进入,但由于安全问题,包裹无法留下。返回单个字符。

  • Y:出于安全考虑,无法保留软件包。
  • N:未指明出于安全考虑,软件包将不会离开。
dpvPbsa

string

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

  • Y:地址已与 PBSA 记录匹配。
  • N:地址与 PBSA 记录不匹配。
dpvDoorNotAccessible

string

该标记表示 USPS 无法敲门以递送邮件的地址。返回单个字符。

  • Y:门无法访问。
  • N:没有指示门无法进入。
dpvEnhancedDeliveryCode

string

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

  • Y:已通过 DPV 确认了主要号码和所有辅助号码的地址。
  • N:未能确认主要号码和任何辅助号码信息。
  • S:地址已针对主号码进行 DPV 确认,而辅助号码信息因未确认而出现,或者主号码的单个尾随 alpha 被丢弃,以使 DPV 匹配并需要辅助信息。
  • D:已仅为主号码确认地址,而辅助号码信息缺失。
  • R:已确认地址但已分配给幻影 R777 和 R779 路线,且未提供 USPS 送货服务。
carrierRoute

string

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

前缀:

  • 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:BUILDING / APARTMENT(住宅)。这是与建筑物或公寓记录匹配的结果。
  • P:邮政信箱这与邮政信箱相匹配。
  • R:RURAL ROUTE 或 HIGHWAY CONTRACT:这与乡村路线或公路合同记录匹配,这两者可能有关联的方框编号范围。
  • 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

双字母州代码。

zipCode

string

邮政编码,例如 10009。

zipCodeExtension

string

扩展 4 位邮编,例如 5023。