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
,但geocodeGranularity
is
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
}
請參閱參考指南中的「判定結果」一節。 |
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 參考資料。
|