修正地址 - 範例

本文說明多種實際情況,在這些情況下,地址驗證 API 會提供回應信號,可能需要系統修正行為。如需相關背景資訊,請參閱範例工作流程,瞭解如何建構驗證邏輯

常見範例:修正

本節說明常見範例,其中 Address Validation API 會提供回應信號,指出地址資訊品質較低。

缺少城市和郵遞區號

這個範例顯示只有街道地址的項目,沒有城市或郵遞區號。

輸入的地址 區域
21 45 40th street USA

缺少城市和郵遞區號的判決

以下範例會強調回應中的重要信號。

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "OTHER",
  "geocodeGranularity": "OTHER",
  "hasUnconfirmedComponents": true,
  "possibleNextAction": "FIX"
}

possibleNextAction初步顯示地址可能無法配送。其他醒目顯示的元件也支援這項功能,因此您可以查詢 addressComponents 來瞭解詳情:

{
  "componentName": {
    "text": "21",
    "languageCode": "en"
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
},
{
  "componentName": {
    "text": "45 40th street",
    "languageCode": "en"
  },
  "componentType": "route",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
},
{
  "componentName": {
    "text": "United States",
    "languageCode": "en"
  },
  "componentType": "country",
  "confirmationLevel": "CONFIRMED"
}

Address Validation API 只會傳回國家/地區 (美國) 做為 CONFIRMED。 系統會以 UNCONFIRMED_BUT_PLAUSIBLE 形式傳回所有其他地址元件,但會省略部分重要資料,例如所在地和郵遞區號。

缺少門牌號碼

這個例子顯示缺少門牌號碼。

輸入的地址 區域
Buckingham Palace Road, SW1W 9TQ London 英國
缺少門牌號碼的判決
{
    "inputGranularity": "PREMISE_PROXIMITY",
    "validationGranularity": "ROUTE",
    "geocodeGranularity": "ROUTE",
    "possibleNextAction": "FIX"
}

同樣地,possibleNextAction 會初步指出地址可能無法送達。此外,validationGranularityROUTE,表示與街道相符,但資訊不足以抵達該處所。此外,判決中缺少 addressComplete 屬性,因此為 false。進一步查詢 address 物件會發現缺少元件類型:

"missingComponentTypes": [
        "street_number"
      ]

邊緣案例範例:修正

在某些情況下,您是否要修正、確認或接受地址,取決於您的特定商家情境。以下範例說明可能不屬於任何修正類別的情況。

未確認的門牌號碼

在此情境中,Address Validation API 無法確認提供的街道號碼,但會指出地址完整。

輸入的地址 區域
84 Buckingham Palace Road, SW1W 9TQ, London 英國

未確認的門牌號碼判決

下例會強調重要信號。

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE_PROXIMITY",
  "geocodeGranularity": "PREMISE_PROXIMITY",
  "addressComplete" : true,
  "hasUnconfirmedComponents": true,
  "possibleNextAction": "ACCEPT"
}

建議您調查驗證精細度組合,只針對未確認的元件進行場所層級的近似值。查詢 addressComponents 屬性會顯示下列未確認的 componentType

{
  "componentName": {
    "text": "84",
    "languageCode": "en"
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}

在此,street_numberstreet_number 會設為 UNCONFIRMED_BUT_PLAUSIBLEconfirmation_level「未確認」表示服務無法在資料集中比對 84 號的街號,而「可能有效」表示元件資料可能仍然有效。

缺少子處所

這個情境是指地址只缺少子處所,例如公寓或部門號碼。否則 Address Validation API 可以完整驗證地址。與缺少任何地址元件的情況相同,addressCompletefalse,因此在手動檢查判決時不會顯示。

舉例來說,假設客戶輸入舊金山市評估員辦公室的有效地址,但輸入時漏了房號。

輸入的地址 區域
1 Doctor Carlton B Goodlett Place, San Francisco, CA 94102 USA

缺少子處所的判決

在本例中,判決結果不會顯示 addressComplete 屬性,因此為 false。因此,您知道至少有一個地址元素是預期外、未解析或遺漏。

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "hasInferredComponents": true,
  "possibleNextAction": "CONFIRM_ADD_SUBPREMISES"
}

address 查詢會顯示以下內容:

"missingComponentTypes": [
        "subpremise"
      ]

進一步查詢後,USPS 資料提供 dpvConfirmation 代碼 D,這也表示缺少子處所。