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 要求,則必須以「PR」的形式提供 addressgoogle.type.PostalAddress.region_code,或提供 addressgoogle.type.PostalAddress.administrative_area 做為「波多黎各」。(不區分大小寫) 或「PR」

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

languageOptions

object (LanguageOptions)

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

啟用 Address Validation API,在回應中加入其他資訊。

sessionToken

string

選用設定。用來識別結算用 Autocomplete 工作階段的字串。必須是網址和檔案名稱安全 Base64 字串,且長度不得超過 36 個 ASCII 字元。否則會傳回 INVALID_src 錯誤。

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

注意:地址驗證只能用於採用 Autocomplete (New) 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 不同。例如,資料庫可能記錄了公寓號碼的存在,但無法提供大型公寓大廈的精確地點位置。在這種情況下,validationGranularitySUB_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 Main Street」的地理編碼。在 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

名稱文字。例如「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)

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

比起地址、經緯度座標或 Plus Code,最好使用地點 ID。在路線規劃或計算行車路線時使用座標,一律會導致點被對齊到最接近這些座標的道路。這可能不是道路很快或安全前往目的地的道路,而且可能不在該地點的存取點附近。此外,如果位置是以反向地理編碼的方式進行地理編碼,系統無法保證傳回的地址會與原始地址相符。

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) 是定位位置參照,可使用兩種格式:使用全域程式碼定義 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」),包含全球代碼的後置字串,並將前置字元換成參照實體的格式化名稱。

可視區域

經緯度可視區域,以對角線的兩點對角線表示 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、郵遞區號和 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:輸入地址 PO、RR 或說明中心方塊號碼
  • P3:輸入的地址 PO、RR 或 HC Box 號碼無效
  • 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 (大專院校、軍事及其他類型) - 將 USPS 納入資料的 ZIP + 4 筆記錄。
  • 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,且次要號碼資訊存在但未確認,或捨棄主要號碼的單一追蹤 Alpha 版,以便比對 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 (私人信箱) 單位指定員。

pmbNumber

string

PMB (私人信箱) 號碼;

addressRecordType

string

符合輸入地址的地址記錄類型。

  • F:FIRM。此資料與公司記錄相符,因為公司記錄是某個地址可用的最佳比對等級。
  • G:一般交付。此項目與「一般遞送」記錄相符。
  • H:建造 / 合夥。這是與建築物或公寓記錄相符的項目。
  • P:張貼作業箱。這是與郵政信箱相符。
  • R:RURAL ROUTE 或 HIGHWAY CONTRACT:這是指與「Rural Route」或「Highway CommitCT」比對結果,兩者都有相關聯的箱號範圍。
  • 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。