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 的參考資料。 |