瞭解基本地址驗證回應

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。

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

地址品質

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

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

請參閱參考指南中的「認定結果」。

address 和 addressComponent 屬性

address 屬性可針對要求中提供的已處理地址提供格式設定，以及地址的元件層級摘要，包括拼錯的部分地址、替換錯誤的部分，以及推測的缺漏部分。

請參閱參考指南中的 Address。

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

請參閱參考指南中的 addressComponent。

geocode 屬性

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

請參閱參考指南中的 Geocode。

metadata 屬性

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

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

uspsData 屬性

這個屬性提供美國郵政地址的實用資訊。 不過，系統不保證能針對服務驗證的每個地址完全填入資料。因此，您不應依賴這項屬性來驗證地址，而應該一併檢查 verdict 和 address。

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