瞭解基本地址驗證回應

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。

地址品質

有許多可能的欄位會指出地址元件的問題，或對地址元件進行調整，例如推測或缺少地址元件。適用對象 舉例來說，下列 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。