瞭解基本地址驗證回應

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 屬性，可針對這項特定要求傳回 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。

地址品質

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

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

address 和 addressComponent 屬性

address 屬性會為要求中提供的已處理地址提供格式，以及地址的元件層級摘要，包括地址的拼寫錯誤部分、已取代不正確部分，以及推斷的遺漏部分。

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

geocode 屬性

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

metadata 屬性

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

uspsData 屬性

這個屬性提供美國郵遞地址的實用資訊。不過，並非每個由服務驗證的地址都能完整填入這些資訊。因此，您不應依賴這個屬性來驗證地址，而應改為檢查 verdict 和 address。