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 必須提供為「Puerto Rico」(不區分大小寫) 或「PR」。

建議您使用元件化的 address,或者另行指定至少兩個 google.type.PostalAddress.address_lines,第一行包含門牌號碼和名稱,第二行包含城市、州/省和郵遞區號。

languageOptions

object (LanguageOptions)

選用設定。預先發布版:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明

讓 Address Validation API 在回應中加入其他資訊。

sessionToken

string

選用設定。用來識別結算用 Autocomplete 工作階段的字串。必須是安全的 base64 字串,且長度不得超過 36 個 ASCII 字元。否則會傳回 INVALID_ARGUMENT 錯誤。

使用者執行自動完成查詢時,工作階段就會開始,並在使用者選取地點並呼叫 PlaceDetails 或 AddressValidation 時結束。每個工作階段都可以有多項 Autocomplete 查詢,後面接著一筆 Place Details 或 Address Validation。在單一工作階段中,每項要求使用的憑證都必須屬於同一個 Google Cloud 控制台專案。工作階段結束後,符記就會失效;您的應用程式必須為每個工作階段產生新的符記。如果省略 sessionToken 參數或重複使用工作階段符記,系統會視為未提供工作階段符記,並針對工作階段收費 (每個要求分別收費)。

注意:Address Validation 只能用於使用 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) - 在使用者使用該欄位的國家/地區外,不應向使用者顯示用於輸入或編輯欄位的 UI 元素。

如要進一步瞭解如何使用這個結構定義,請參閱: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 留白,改用 addressLines。

sublocality

string

選用設定。地址的縣市以下行政區,例如社區、自治市鎮和區等。

addressLines[]

string

必要欄位。非結構化的地址行,說明地址的低層級項目。

由於 addressLines 中的值不會有類型資訊,而且有時在單一欄位中可能會包含多個值 (例如「Austin, TX」),因此地址行的順序務必要明確。地址行的順序應為該地址所在國家/地區的「信封書寫順序」。

地址允許的最小結構表示法是包含所有資訊放置在 addressLines 中。如果未提供 regionCode,系統會根據地址行推斷區域。

如要處理完全非結構化的地址,我們建議您只建立包含 addressLines 的地址,並使用地理定位來進行 (而非猜測地址的哪些部分應該是縣市還是行政區)。

recipients[]

string

請勿設定此欄位。Address Validation API 目前並未使用。雖然目前 API 不會拒絕含有此欄位的請求,但系統會捨棄該資訊,不會在回應中傳回。

organization

string

請勿設定此欄位。Address Validation API 目前並未使用。雖然目前 API 不會拒絕含有此欄位設定的要求,但系統會捨棄該資訊,不會在回應中傳回。

LanguageOptions

預先發布版:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明

啟用 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)

其他與可送達性相關的資訊。metadata 不保證會為傳送至 Address Validation API 的每個地址完整填入資料。

uspsData

object (UspsData)

USPS 提供的額外交付項目標記。僅提供 USPR 區域。

englishLatinAddress

object (Address)

預覽:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明

已翻譯成英文的地址。

翻譯的地址無法用於 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 可完整驗證位址的精細程度。舉例來說,PREMISEvalidationGranularity 表示能驗證 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。不過,如果我們找不到位於 Redwood City 的「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 欄位中的地址格式不符。舉例來說,postalAddress 一律以 2 個字母 regionCode 表示國家/地區,例如「US」或「NZ」。相較之下,這個欄位會使用較長的國家/地區名稱,例如「美國」或「紐西蘭」。

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

輸入資料中有任何無法解析的權杖。這可能是系統無法辨識為有效地址的輸入內容。舉例來說,如果輸入的內容是「Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US」,未解析的符記可能會是 ["Parcel", "0000123123", "&", "0000456456"]

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

名稱文字。例如街道名稱「5th Avenue」或門牌號碼「1253」。

languageCode

string

BCP-47 語言代碼。如果元件名稱未與語言 (例如門牌號碼) 建立關聯,就不會顯示。

ConfirmationLevel

確認層級的不同可能值。

列舉
CONFIRMATION_LEVEL_UNSPECIFIED 預設值。這個值未使用。
CONFIRMED 我們可驗證該元件是否存在,且與地址的其他內容一致。
UNCONFIRMED_BUT_PLAUSIBLE 我們無法確認這個元件,但它可能存在。例如,在街道上,門牌號碼位於已知有效範圍內,但具體門牌號碼不明。
UNCONFIRMED_AND_SUSPICIOUS 這個元件未經確認,可能有誤。例如,不符合地址其餘部分的鄰里。

Geocode

包含輸入內容經過地理編碼後的地點資訊。

JSON 表示法
{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}
欄位
location

object (LatLng)

輸入內容的地理編碼位置。

建議您使用地點 ID,而非地址、經緯度座標或 Plus Code。在規劃路線或計算行車路線時使用座標,系統一律會將點對齊最接近該座標的道路。這條路可能無法快速或安全地通往目的地,也可能不在房源附近。此外,當位置經過反向地理編碼後,傳回的地址不一定會與原始地址相符。

plusCode

object (PlusCode)

location 相應的 Plus Code。

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) 是一種位置參照,有兩種格式:全球代碼定義 14 公尺 x 14 公尺 (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

地址的中繼資料。metadata 不保證會為傳送至 Address Validation API 的每個地址完整填入資料。

JSON 表示法
{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}
欄位
business

boolean

表示這是商家地址。如果未設定,則表示值不明。

poBox

boolean

表示郵政信箱的地址。如果未設定,則表示值不明。

residential

boolean

表示這是住家地址。如未設定,表示該值不明。

UspsData

地址的 USPS 資料。uspsData 不保證會為每個傳送至 Address Validation API 的美國或波多黎各地址完整填入資料。如果您將 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、郵遞區號和郵遞區號 + 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:輸入的地址 PO、RR 或 HC 信箱號碼無效
  • F1:輸入與軍事地址相符的地址
  • G1:輸入與一般寄送地址相符的地址
  • U1:輸入的地址與不重複的郵遞區號相符
  • PB:輸入的地址與 PBSA 記錄相符
  • RR:DPV 已確認地址,並提供 PMB 資訊
  • R1:DPV 確認地址,但沒有 PMB 資訊
  • R7:航空公司路線 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 (大學、軍事和其他類型) - 美國郵政署已納入資料的郵遞區編號 + 4 記錄。
  • 5:一般 - 表示地址未收到郵件,且系統不會將這些地址視為可能的送達地址。
  • 6:需要次要資訊 - 地址需要次要資訊。
dpvDrop

string

標記表示郵件已送至網站上的單一收件匣。傳回單一字元。

  • Y:郵件會送至網站上的單一收件匣。
  • N:郵件並非遞送至網站的單一接待員。
dpvThrowback

string

表示郵件未送達街道地址。傳回單一字元。

  • Y:郵件未送達街道地址。
  • N:郵件會送到街道地址。
dpvNonDeliveryDays

string

此標記表示郵件並非在每週的每一天送達。傳回單一字元。

  • Y:系統不會在一週內每天傳送郵件。
  • N:沒有郵件傳送時間表,無法確認郵件並非每週的每一天都會送達。
dpvNonDeliveryDaysValues

integer

整數,用於識別未放送日。您可以使用位元旗標查詢:0x40 – 週日為非送達日 0x20 – 週一為非送達日 0x10 – 週二為非送達日 0x08 – 週三為非送達日 0x04 – 週四為非送達日 0x02 – 週五為非送達日 0x01 – 週六為非送達日

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

貨運公司的路由代碼。四個字元的代碼,包含一個英文字母前置字串和三位數路線標記。

前置字串:

  • 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 (Private Mail Box) 單位指標。

pmbNumber

string

PMB (Private Mail Box) 號碼

addressRecordType

string

與輸入地址相符的地址記錄類型。

  • F:FIRM。此資料與公司記錄相符,因為公司記錄是某個地址可用的最佳比對等級。
  • G:一般運送。這項資訊與一般寄送記錄相符。
  • H:建造 / 合夥。這項資料與建築物或公寓記錄相符。
  • P:郵政信箱。這是與郵政信箱的比對結果。
  • R:RURAL ROUTE 或 HIGHWAY CONTRACT:與 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。