瞭解基本地址驗證回應

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": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

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

請參閱參考指南中的「判決」。

地址的細分程度

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

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

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

地址是否完整

判決結果會將 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
}
請參閱參考指南中的「判決」。

可能的後續動作

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

address 和 addressComponent 屬性

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

請參閱參考指南中的 Address。

addressComponent 屬性是 address 的子元件，提供地址元素 (或元件) 的詳細清單，這些元素已由 Maps JavaScript API 中的 Address Validation 處理。API 會依據每個元件欄位的名稱、類型和確認層級進行識別。

請參閱參考指南中的 addressComponent。

geocode 屬性

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

請參閱參考指南中的 Geocode。

metadata 屬性

對於 Maps JavaScript API 中地址驗證處理的每個地址，這個屬性可能不會填入，但會指出地址類型為住宅、商家或郵政信箱。

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

uspsData 屬性

這項屬性可提供美國郵寄地址的實用資訊。 不過，服務不保證會為驗證的每個地址填入完整資訊。因此，您不應只依據這項屬性驗證地址，而是應同時檢查 verdict 和 address。

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