瞭解基本地址驗證回應

地址驗證 API 會以 JSON 物件的形式提供回應主體，其中包含兩個頂層屬性：

{
  "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 屬性中的所有欄位。

請參閱參考指南中的「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 屬性表示地址含有未確認的元件，且缺少 addressComplete 欄位：

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
請參閱參考指南中的「判決」Verdict。

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 的參考資料。
上一頁
傳送地址驗證要求
下一頁
建構驗證邏輯