瞭解基本地址驗證回應

注意： 本文件說明適用於高品質地址的地址驗證回應基本元素。如要瞭解如何處理實際地址情境，以及針對更複雜的回應建構邏輯，請參閱「建構驗證邏輯」一文。

Address Validation API 提供回應主體做為 JSON 物件，其中包含兩個頂層屬性：

• result，ValidationResult 類型的物件
• responseID

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

本文件著重於 result 物件。如要瞭解 responseID，請參閱「處理更新後的地址」。

verdict 屬性

重點提示： 使用 verdict 屬性取得地址品質的基準摘要。

verdict 屬性會總結地址驗證的結果，且在建構地址檢查邏輯時，應是第一個要評估的屬性。屬性可能會根據輸出地址的品質傳回各種欄位。舉例來說，以下顯示品質良好地址的 verdict 屬性，該屬性會針對此特定要求傳回 4 個欄位：

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true
}

以下各節概略說明 verdict 屬性中的所有欄位。

請參閱參考指南中的「判定結果」一節。

地址精細程度

地址精細程度是指用來判斷地址或地理編碼詳細程度的精細程度。validationGranularity 回應中的位址明確性是判斷地址能否送達的關鍵信號。

verdict 屬性會傳回以下精細程度信號：

• inputGranularity — 說明從傳送至 Address Validation API 的地址中擷取的精細程度。要求中的地址詳細資料層級會影響驗證回應中的地址詳細資料層級。舉例來說，inputGranularity 低於 PREMISE 層級的地址通常不會導致 validationGranularity 變為 PREMISE 層級。
• validationGranularity：Address Validation API 可完整驗證地址的精細程度。在大多數情況下，PREMISE 或 SUB_PREMISE 的精細程度代表可能送達的品質地址。
• geocodeGranularity：說明與地址相關聯的地理編碼詳細程度。例如，Google 記錄可能顯示公寓號碼存在，而非大型公寓大樓內該特定公寓的精確位置。在這種情況下，validationGranularity 為 SUB_PREMISE，但 geocodeGranularityisPREMISE`。

請參閱參考指南中的精細程度。

地址的完整性

判定結果會傳回 addressComplete 屬性做為高品質位址的信號，這表示它沒有遺漏、未解析或非預期的元件：

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true
}

當地址缺少、未解析或非預期的元件時，欄位會設為 false。

注意： 如果 addressComplete 屬性未出現在手動檢查的判定結果中，其值則為 false。視您的程式設計語言而定，您可以查詢判定結果是否有 addressComplete 屬性，或直接查詢屬性。請參閱下方的地址品質範例。

請參閱參考指南中的「判定」和「地址」下方的 addressComplete。

地址品質

許多可能的欄位表示地址元件有問題，或地址元件的調整，例如推測或遺漏的地址元件。舉例來說，下列 verdict 屬性表示含有未確認元件且缺少 addressComplete 欄位的地址：

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

請參閱參考指南中的「判定結果」一節。

address 和 addressComponent 屬性

重點提示： 使用 address 屬性取得地址格式。請使用其子元件 addressComponent 來調查錯誤，並向客戶提供這些錯誤的相關資訊。不過，請勿建構整合作業以依賴地址元件的特定確認層級。如需整合指南，請參閱「建構驗證邏輯」一文。

address 屬性可為要求中提供的已處理地址提供格式，以及地址的元件層級摘要，包括地址拼字有誤的部分、遭到取代的錯誤部分，以及推測出的遺漏部分。

請參閱參考指南中的 Address。

addressComponent 屬性是 address 的子元件，可提供 Address Validation API 處理的地址元素 (或元件) 詳細清單。API 會根據名稱、類型和確認層級來識別每個元件欄位。

請參閱參考指南中的 addressComponent。

geocode 屬性

重點提示： 如果您先前的邏輯是呼叫 Geocoding API，使用 geocode 屬性即可輕鬆取得地理編碼或地點 ID。

geocode 屬性表示與輸入地址相關聯的地理編碼位置。這個屬性提供地點本身的詳細資料，例如地點 ID。

請參閱參考指南中的 Geocode。

metadata 屬性

重點提示： 使用 metadata 屬性判斷與地址相關聯的房源類型：住宅、郵政信箱或商家。

這個屬性可能不會為 Address Validation API 處理的每個地址填入這項屬性，但會顯示地址是住宅、商家或郵政信箱。

請參閱 Address Validation API 涵蓋範圍和 Address metadata 的參考資料。

uspsData 屬性

重點： 使用 uspsData 屬性取得美國地址的寄送信賴水準和其他 USPS 詳細資料。

這個屬性提供美國郵寄地址的實用資訊。 不過，我們不保證會完整填入服務驗證的每個地址。因此，您不應依賴此屬性做為唯一驗證地址的方式，而是一併檢查 verdict 和 address。

請參閱「處理美國地址」和 UspsData 參考資料。