瞭解基本地址驗證回應

地址驗證 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,
  "possibleNextAction": "ACCEPT"
}

以下各節會摘要說明 verdict 屬性中的所有欄位。

可能採取的後續行動

possibleNextAction 屬性會提供 API 回應中其餘部分的解讀摘要，協助您判斷是否應提示顧客檢查或編輯地址。詳情請參閱建構驗證邏輯。

地址的精細程度

地址精細度是指用於判斷地址或地理編碼具體程度的詳細程度。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,
    "possibleNextAction": "ACCEPT"
}

如果地址缺少、無法解析或包含非預期元件，系統會將該欄位設為 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。