瞭解基本地址驗證回應

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 屬性表示與輸入內容相關聯的地理編碼位置 讓我們看看 DNS 解析 進一步探索內部和外部位址這個屬性提供位置本身的詳細資料，例如地點 ID。

metadata 屬性

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

uspsData 屬性

這個屬性提供美國郵政地址的實用資訊。 不過，不保證每個地址都會完整填入 以及服務本身因此，我們不建議您使用 只能驗證地址，而是檢查 verdict 和 address。