瞭解基本地址驗證回應

注意： 本文件說明高品質地址的地址驗證回應基本元素。如需處理實際地址情境，以及建構更複雜回應邏輯的指引，請參閱「建構驗證邏輯」。

Address Validation API 回應包含下列頂層屬性：

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // 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"
}

verdict 屬性

重點： 使用 verdict 屬性，取得地址品質的基準摘要。

verdict 屬性會匯總地址驗證結果，建構地址檢查邏輯時，應優先評估這項屬性。這項屬性可傳回多種欄位，具體取決於輸出地址的品質。舉例來說，以下是優質地址的 verdict 屬性，會針對這項特定要求傳回下列欄位：

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

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

請參閱參考指南中的「Verdict」一節。

地址精細程度

地址精細程度是指用來判斷地址或地理編碼具體程度的詳細程度。validationGranularity 回應中的地址明確程度，是判斷地址是否可送達的重要信號。

verdict 屬性會傳回下列精細程度信號：

• inputGranularity：說明從傳送至 Maps JavaScript API 中「地址驗證」的地址擷取的詳細程度。要求中的地址詳細程度會影響驗證回應中的地址詳細程度。舉例來說，如果地址的 inputGranularity 低於 PREMISE 等級，通常不會 validationGranularity 到 PREMISE 等級。
• validationGranularity：Maps JavaScript API 中的地址驗證功能可完整驗證地址的精細程度。在多數情況下，精細程度為 PREMISE 或 SUB_PREMISE 表示地址品質良好，可能可以送達。
• geocodeGranularity：說明與地址相關聯的地理編碼詳細程度。舉例來說，Google 記錄可能指出某個公寓號碼存在，但無法指出該公寓在大型公寓建築群中的精確位置。在這種情況下，validationGranularity 為 SUB_PREMISE，但 geocodeGranularity 為 PREMISE。

請參閱參考指南中的「精細程度」一節。

地址完整性

判定結果會傳回 addressComplete 屬性，做為高品質地址的信號，具體來說，這表示地址沒有遺漏、未解析或非預期的元件：

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true
}

如果地址缺少、未解析或含有非預期元件，系統會將這個欄位設為 false。

注意： 如果手動檢查後，判定結果中未顯示 addressComplete 屬性，則其值為 false。在這種情況下，您應查詢判定結果中是否有 addressComplete 屬性，或直接查詢該屬性。請參閱下方的「地址品質」範例。

請參閱參考指南中「Verdict」和「Address」下方的 addressComplete。

地址品質

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

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

請參閱參考指南中的「判定」一節。

可能的後續行動

這項產品/功能為預先發布版 (正式發布前)。我們對於正式發布前的產品和功能僅提供有限度的支援。此外，這類產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範，詳情請參閱推出階段說明。

possibleNextAction 判定結果欄位提供 API 回應的解讀摘要，協助您判斷後續可能採取的行動。這個欄位衍生自 API 回應中的其他欄位，不應視為地址準確性或可送達性的保證。

address 和 addressComponent 屬性

重點提示： 請使用 address 屬性取得地址格式。請使用其子元件 addressComponent 調查錯誤，並向客戶提供這些錯誤的相關資訊。不過，請勿將整合功能建構為依賴地址元件的特定確認層級。如需整合指南，請參閱「建構驗證邏輯」。

address 屬性會提供要求中處理地址的格式，以及地址的元件層級摘要，包括地址中拼寫錯誤的部分、替換的錯誤部分，以及推論出的遺漏部分。

請參閱參考指南中的 Address。

addressComponent 屬性是 address 的子元件，可詳細列出 Maps JavaScript API 中「地址驗證」處理過的地址元素或元件。API 會依名稱、類型和確認等級，識別每個元件欄位。

請參閱參考指南中的 addressComponent。

geocode 屬性

重點提示： 如果邏輯先前呼叫過 Geocoding API，請使用 geocode 屬性，方便取得地理編碼或地點 ID。

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

請參閱參考指南中的 Geocode。

metadata 屬性

重點： 使用 metadata 屬性，判斷與地址相關聯的房產類型：住宅、郵政信箱或商家。

Maps JavaScript API 的地址驗證功能處理的地址，不一定都會填入這個屬性，但會指出地址類型是住宅、商家或郵政信箱。

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

uspsData 屬性

重點： 使用 uspsData 屬性，取得美國地址的送達信心水準和其他 USPS 詳細資料。

這項屬性可提供美國郵政地址的實用資訊。不過，服務驗證的每個地址不一定都會完整填入這項資訊。因此，請勿僅依賴這項屬性驗證地址，而應一併檢查 verdict 和 address。

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