本文件說明瞭許多實際情境,其中 Address Validation API 會針對需要系統確認的地址提供回應信號。如需背景資訊,請參閱「建立驗證邏輯」一文中的工作流程總覽。
常見範例:確認
以下範例說明都會區中相似的街道名稱。假設使用者想輸入 位於美國華盛頓州 Kirkland 的 Google 大樓 D 棟地址。不過,他們在輸入城市時,不小心輸入 Seattle,而非 Kirkland。
輸入的地址 | 區域 |
---|---|
451 7th Avenue South, Seattle, WA 98033 的 D 棟 | 美國 |
取代資料的判定結果
以下範例強調回應中的重點信號。
{
"inputGranularity": "SUB_PREMISE",
"validationGranularity": "PREMISE_PROXIMITY",
"geocodeGranularity": "PREMISE_PROXIMITY",
"addressComplete": true,
"hasUnconfirmedComponents": true
"hasReplacedComponents": true
}
PREMISE_PROXIMITY
表示建築物層級地址的近似值,但不如 SUB_PREMISE
詳細,後者是輸入時提供的精細度。回應也包含未確認和已取代的元件,因此這類組合會歸入「確認」類別。
對地址元件進行查詢後,發現下列疑慮事項:
{
"componentName": {
"text": "451",
},
"componentType": "street_number",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
...
{
"componentName": {
"text": "98104",
},
"componentType": "postal_code",
"confirmationLevel": "CONFIRMED",
"replaced": true
}
...
{
"componentName": {
"text": "Building D",
"language_code": "en"
},
"componentType": "subpremise",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
.......
"unconfirmedComponentTypes": [
"street_number",
"subpremise"
]
在本例中,Address Validation API 找到與提供的 Seattle 地址相近的地址,並將郵遞區號 (較高層級的元件) 替換為 Seattle 地址。這可能是有效的替換項目,但考量到元件未經確認,因此建議確認使用者是否要輸入西雅圖的地址,而非其他地址,例如 Kirkland。
極端案例示例:確認
以下範例說明以下邊緣情況類型:
- 已確認的次要推論。Address Validation API 會推斷國家/地區、郵遞區號或州/省,但其他所有資訊都會提供並確認。精細度和確認層級的組合可讓次要推論不一定需要確認動作。
- 未確認意外的地址元件。未經確認的地址元件會提高地址的風險等級。這可能需要確認。
- 已確認的非預期地址元件。這個元件並非正確地址的必要元素,Address Validation API 會將其從輸出內容中移除。格式設定問題通常不需確認。
已確認的次要推論
結合更精細層級的已確認資料後,如果輸入內容只缺少下列類型中的一個元件,API 仍可做出正確推論:
- 城市
- 州
- 郵遞區號
- 國家/地區
舉例來說,客戶提供位於麻薩諸塞州斯普林菲爾德的麥當勞餐廳有效街道地址,但忘記輸入城市,並提供沒有 4 位數擴充字元的郵遞區號。
輸入的地址 | 區域 |
---|---|
1402 Allen St, MA 01118 | 美國 |
判定結果:缺少城市
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true,
"hasInferredComponents": true
}
如果 Address Validation API 會推斷較高層級的元件,以產生可送達的地址,您就能更有信心判斷系統提供的資料是否正確。這是因為代表廣大地理區域的推測元件,更容易與精細度較高的已確認地址元件進行比對。即使在城市名稱重複的國家/地區 (例如美國的春田鎮),只要搭配其他元件,仍可提供不重複的地址。
以上述範例來說,掃描所有地址元件後,系統會顯示每個元件均已確認,也就是說,這些元件與 Address Validation API 儲存的資料相符,且服務也會推斷兩個較高層級的元件。
{
"componentName": {
"text": "Springfield",
"languageCode": "en"
},
"componentType": "locality",
"confirmationLevel": "CONFIRMED",
"inferred": true
},
{
"componentName": {
"text": "1806"
},
"componentType": "postal_code_suffix",
"confirmationLevel": "CONFIRMED",
"inferred": true
}
系統未確認意外的地址元件
這個情境說明瞭檢查元件「未」確認的重要性。如果地址元件不符合預期,Address Validation API 會將該元件從輸出內容中移除。在這種情況下,您可以根據風險程度和信心程度,接受地址或向客戶重新確認。
舉例來說,某個地區的客戶經常會輸入郵局會忽略的無害資訊,在這種情況下,您可以接受該地址。不過,在某些情況下,未經確認的元件可能不是客戶想要的。
輸入的地址 | 區域 |
---|---|
1 Rue Grenache, la caritat 2, 34630 Saint-Thibéry | 法國 |
判定結果:未確認非預期的地址元件
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"unconfirmedComponents": true
}
除了包含未確認元件的判定結果外,Address Validation API 也會傳回以下格式化的地址:
"formattedAddress": "1 Rue Grenache, 34630 Saint-Thibéry, France",
掃描未確認的元件後,我們發現 API 已從傳回的地址中移除 la caritat 2:
{
"componentName": {
"text": "la caritat 2",
"languageCode": "fr"
},
"componentType": "sublocality_level_1",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
"unexpected": true
}
已確認的非預期地址元件
本例說明如何在提供的地址中加入英國郡,這是常見的做法。不過,這並非英國郵政機構的要求,因此基本上會遭到忽略。請參閱 postoffice.co.uk 和如何寫英國和國際郵件地址。
因此,當客戶在英國地址中提供縣名時,服務會將其視為非預期輸入內容。
輸入的地址 | 區域 |
---|---|
33 Dunalley St, Cheltenham, Gloucestershire, GL50 4AP | 英國 |
確認不符預期的地址元件判定結果
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE"
}
在此例中,address_complete
的評估結果為 false,而對地址元件的分析顯示了非預期的旗標。
{
"componentName": {
"text": "Gloucestershire",
"languageCode": "en"
},
"componentType": "administrative_area_level_2",
"confirmationLevel": "CONFIRMED",
"unexpected": true
}
雖然 Gloucestershire 是輸入地址的正確縣,但地址本身的格式不正確。請注意,Address Validation API 也會評估資訊是否採用正確的格式。