Method: validateAddress

驗證地址。

HTTP 要求

POST https://addressvalidation.googleapis.com/v1:validateAddress

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體的資料會採用以下結構:

JSON 表示法
{
  "address": {
    object (PostalAddress)
  },
  "previousResponseId": string,
  "enableUspsCass": boolean,
  "languageOptions": {
    object (LanguageOptions)
  },
  "sessionToken": string
}
欄位
address

object (PostalAddress)

必要欄位。要驗證的地址。未設定格式的地址應透過 addressLines 提交。

這項輸入欄位中的欄位總長度不得超過 280 個半形字元。

支援的地區請參閱這裡

輸入地址中的 languageCode 值會保留供日後使用,今天會遭到忽略。系統會根據系統找出的指定地址偏好語言,填入經過驗證的地址結果。

Address Validation API 會忽略 recipientsorganization 中的值。這些欄位中的所有值都會遭到捨棄,不會傳回。請不要設定這類標記。

previousResponseId

string

首次地址驗證要求時,這個欄位必須留空。如果需要更多要求才能完整驗證單一地址 (例如,若使用者在初始驗證後所做的變更需要重新驗證),則每個後續要求都必須在驗證序列中第一個回應內,將 responseId 填入這個欄位。

enableUspsCass

boolean

啟用 USPS CASS 相容模式。這項操作只會影響 google.maps.addressvalidation.v1.ValidationResultgoogle.maps.addressvalidation.v1.ValidationResult.usps_data 欄位。注意:如果是啟用波多黎各地址的 USPS CASS 要求,須以「PR」形式提供 addressgoogle.type.PostalAddress.region_code,或是 addressgoogle.type.PostalAddress.administrative_area (不區分大小寫) 或「PR」。

建議您使用元件化的 address,或是指定至少兩個 google.type.PostalAddress.address_lines (第一行包含街道號碼和名稱,第二行包含城市、州和郵遞區號)。

languageOptions

object (LanguageOptions)

選用設定。預先發布版:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明

啟用 Address Validation API,在回應中加入其他資訊。

sessionToken

string

選用設定。用於識別計費 Autocomplete 工作階段的字串。必須是網址和檔案名稱安全 Base64 字串,長度上限為 36 個 ASCII 字元。否則系統會傳回 INVALID_UNIT 錯誤。

工作階段從使用者提出 Autocomplete 查詢時起算,直到使用者選取地點,並呼叫 Place Details 或 Address Validation 時結束。每個工作階段可包含多個 Autocomplete 查詢,後面接著一個 Place Details 或 Address Validation 要求。工作階段內每個要求使用的憑證,必須隸屬於同一個 Google Cloud 控制台專案。工作階段結束後,符記就會失效;應用程式必須為每個工作階段產生新的符記。如果省略 sessionToken 參數或重複使用工作階段符記,系統會視為未提供工作階段符記,並針對工作階段收費 (每個要求分別收費)。

注意:Address Validation 僅適用於搭配 Autocomplete (New) API 的工作階段,而非 Autocomplete API。詳情請參閱 https://developers.google.com/maps/documentation/places/web-service/session-pricing

回應主體

地址驗證要求的回應。

如果成功,回應主體即會包含具有以下結構的資料:

JSON 表示法
{
  "result": {
    object (ValidationResult)
  },
  "responseId": string
}
欄位
result

object (ValidationResult)

地址驗證的結果。

responseId

string

用於識別此回應的 UUID。如果地址需要重新驗證,這個 UUID「必須」隨新要求一併驗證。

PostalAddress

表示郵寄地址,如郵政快遞或付款地址。如果是郵寄地址,郵政服務可將貨品寄送到場所、郵政信箱或類似位置。此表示法並不適用於建立地理位置 (街道、鄉鎮或山區) 的模型。

在一般使用情況下,系統會根據處理作業的類型,以使用者輸入或匯入現有資料的方式來建立地址。

地址輸入/編輯建議:使用支援國際化的地址小工具,例如 https://github.com/google/libaddressinput)。在使用該欄位的國家/地區之外,不應向使用者顯示用於輸入或編輯欄位的 UI 元素。

如要進一步瞭解如何使用這個結構定義,請參閱:https://support.google.com/business/answer/6397478

JSON 表示法
{
  "revision": integer,
  "regionCode": string,
  "languageCode": string,
  "postalCode": string,
  "sortingCode": string,
  "administrativeArea": string,
  "locality": string,
  "sublocality": string,
  "addressLines": [
    string
  ],
  "recipients": [
    string
  ],
  "organization": string
}
欄位
revision

integer

PostalAddress 的結構定義修訂版本。除 0 以外的值將會導致 API 傳回 INVALID_ARGUMENT 錯誤。

regionCode

string

選用設定。地址所在國家/地區的 CLDR 地區代碼。詳情請參閱 https://cldr.unicode.org/https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html。例如:瑞士的字為「CH」。如未提供區碼,系統將從地址推斷。為獲得最佳效能,建議您加入區碼 (如果知道的話)。區域不一致或重複可能會導致效能不佳,例如,如果 addressLines 已包含該區域,請勿在這個欄位中再次提供區碼。請參閱常見問題,瞭解支援的地區。

languageCode

string

輸入地址中的語言代碼僅供日後使用,現已遭到忽略。API 會以適當語言傳回地址所在位置的地址。

postalCode

string

選用設定。地址的郵遞區號。並非所有國家/地區都使用郵遞區號或要求必須填寫郵遞區號,不過在使用郵遞區號時,可能會對地址其他部分觸發額外的驗證作業 (例如美國對州/郵遞區號的驗證)。

sortingCode

string

選用設定。國家/地區專屬的其他分類代碼。大多數國家/地區並不使用這個代碼。在使用分類代碼的國家/地區中,這個值為與「CEDEX」相似的字串,後面選擇性加上一個數字 (例如「CEDEX 7」),或是只有單一數字,並用來表示「區段代碼」(牙買加)、「寄送區域指示碼」(馬拉威) 或「郵局指示碼」(如象牙海岸)。

administrativeArea

string

選用設定。最高行政區,用於國家/地區的郵遞地址。例如,此值可以是州、省或縣。以西班牙為例來具體說明,此欄位的值為省,而非自治區 (例如「巴塞隆納」省,而不是「加泰隆尼亞」自治區)。許多國家/地區的郵寄地址並沒有使用行政區。例如,就瑞士而言,該欄位應該留空不填。

locality

string

選用設定。一般是指地址的縣市/鄉鎮部分。例如:美國城市、義大利市鎮、英國郵鎮。如為未明確定義縣市或其縣市不適用此結構的地區,請將 locality 留白,改用 addressLines。

sublocality

string

選用設定。地址的縣市以下行政區,例如社區、自治市鎮和區等。

addressLines[]

string

必要欄位。非結構化的地址行,說明地址的低層級項目。

由於 addressLines 中的值不會有類型資訊,而且有時在單一欄位中可能會包含多個值 (例如「Austin, TX」),因此地址行順序必須明確。地址行的順序應為地址所在國家/地區的「信封訂單」。

地址允許的最小結構表示法包含 addressLines 中的所有資訊。如果未提供 regionCode,系統會從地址行推測區域。

如要處理完全非結構化的地址,建議您建立只含有 addressLines 的地址,再使用地理編碼 (而非猜測地址的哪些部分應該是縣市或行政區)。

recipients[]

string

請避免設定這個欄位。Address Validation API 目前並未使用。API 目前不會拒絕包含這個欄位集的要求,但資訊會遭到捨棄,且不會在回應中傳回。

organization

string

請避免設定這個欄位。Address Validation API 目前並未使用。API 目前不會拒絕包含這個欄位集的要求,但資訊會遭到捨棄,且不會在回應中傳回。

LanguageOptions

預先發布版:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明

啟用 Address Validation API,在回應中加入其他資訊。

JSON 表示法
{
  "returnEnglishLatinAddress": boolean
}
欄位
returnEnglishLatinAddress

boolean

預覽:以英文傳回 google.maps.addressvalidation.v1.Address。詳情請參閱 google.maps.addressvalidation.v1.ValidationResult.english_latin_address

ValidationResult

驗證地址的結果。

JSON 表示法
{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  },
  "englishLatinAddress": {
    object (Address)
  }
}
欄位
verdict

object (Verdict)

整體判定結果標記

address

object (Address)

地址本身 (而非地理編碼) 的資訊。

geocode

object (Geocode)

取得地址地理編碼的位置和地點的相關資訊。

metadata

object (AddressMetadata)

與交付功能有關的其他資訊。我們不保證會針對傳送至 Address Validation API 的每個地址填入 metadata

uspsData

object (UspsData)

USPS 提供的額外傳送性旗標。僅在 USPR 地區提供。

englishLatinAddress

object (Address)

預先發布版:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明

地址已翻譯成英文。如果地址的一部分未提供英文翻譯,服務會以拉丁字母系統的替代語言傳回該部分地址。如需瞭解如何選擇替代語言,請參閱這裡的說明。如果地址其中一部分沒有使用拉丁字母語言之翻譯或音譯,服務會以與地址相關聯的當地語言傳回該部分。

您使用 google.maps.addressvalidation.v1.LanguageOptions.return_english_latin_address 標記啟用此輸出。

注意:englishLatinAddress 中的 google.maps.addressvalidation.v1.Address.unconfirmed_component_types 欄位和 englishLatinAddress.address_components 中的 google.maps.addressvalidation.v1.AddressComponent.confirmation_level 欄位並未填入資料。

評斷

地址驗證結果和地理編碼的概要總覽。

JSON 表示法
{
  "inputGranularity": enum (Granularity),
  "validationGranularity": enum (Granularity),
  "geocodeGranularity": enum (Granularity),
  "addressComplete": boolean,
  "hasUnconfirmedComponents": boolean,
  "hasInferredComponents": boolean,
  "hasReplacedComponents": boolean
}
欄位
inputGranularity

enum (Granularity)

輸入位址的精細程度。也就是剖析輸入地址的結果,並不會提供任何驗證信號。如要瞭解驗證信號,請參閱下方的 validationGranularity

舉例來說,如果輸入的地址含有特定公寓號碼,則這裡的 inputGranularity 會是 SUB_PREMISE。如果我們無法比對資料庫中的公寓號碼,或公寓號碼無效,validationGranularity 可能為 PREMISE 或以下。

validationGranularity

enum (Granularity)

API 可完整「驗證」validate地址的目標精細程度。舉例來說,如果 validationGranularityPREMISE,代表可以驗證 PREMISE 不精確層級的所有地址元件。

每個地址元件的驗證結果可在 google.maps.addressvalidation.v1.Address.address_components 中找到。

geocodeGranularity

enum (Granularity)

geocode 精細程度的相關資訊。您可以理解為精確或精細調整地理編碼位置的語意含義。

這有時會與上方的 validationGranularity 不同。舉例來說,我們的資料庫可能會記錄某個公寓號碼的存在,但對於大型公寓大樓內的公寓沒有確切位置。在此情況下,validationGranularity 會是 SUB_PREMISE,但 geocodeGranularity 會是 PREMISE

addressComplete

boolean

如果沒有未解析的權杖、沒有非預期或遺漏的地址元件,系統會將地址視為「完整」。詳情請參閱 missingComponentTypesunresolvedTokensunexpected 欄位。

hasUnconfirmedComponents

boolean

至少有一個地址元件無法分類或驗證,詳情請參閱 google.maps.addressvalidation.v1.Address.address_components

hasInferredComponents

boolean

系統判定至少有一個地址元件不是輸入的內容所推測 (已新增),詳情請參閱 google.maps.addressvalidation.v1.Address.address_components

hasReplacedComponents

boolean

至少一個地址元件已被取代,詳情請參閱 google.maps.addressvalidation.v1.Address.address_components

精細程度

地址或地理編碼的各種精細程度。用來表示「地址」的精細程度時,這些值代表地址識別郵件目的地的精細程度。例如,「123 Main Street, Redwood City, CA, 94061」這類地址可識別 PREMISE,而「Redwood City, CA, 94061」則代表 LOCALITY。不過,如果我們無法在紅木市找到「123 Main Street」的地理編碼,則傳回的地理編碼可能會是 LOCALITY 的精細度。

列舉
GRANULARITY_UNSPECIFIED 預設值。未使用這個值。
SUB_PREMISE 位於建築物等級下方的結果,例如公寓。
PREMISE 建築物層級結果。
PREMISE_PROXIMITY 推估地址的建築物層級位置的地理編碼。
BLOCK 地址或地理編碼會指出一個區塊。只用於具有區塊層級定址的區域,例如日本。
ROUTE 地理編碼或地址的精細程度是路線,例如街道、道路或高速公路。
OTHER 其餘的精細程度則會聚集在一起,因為這類項目無法傳送。

地址

處理後地址的詳細資料。後續處理包括修正地址中錯字的部分、替換不正確的部分,以及推斷缺漏的部分。

JSON 表示法
{
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "addressComponents": [
    {
      object (AddressComponent)
    }
  ],
  "missingComponentTypes": [
    string
  ],
  "unconfirmedComponentTypes": [
    string
  ],
  "unresolvedTokens": [
    string
  ]
}
欄位
formattedAddress

string

依地址所在區域的地址格式規則後處理的地址,格式為單行地址。

postalAddress

object (PostalAddress)

後處理地址,以郵寄地址表示。

addressComponents[]

object (AddressComponent)

未排序的清單。格式化地址的個別地址元件和驗證資訊。以便瞭解個別元件的驗證狀態。

地址元件不依特定順序排列。請勿假設清單中地址元件的順序。

missingComponentTypes[]

string

應該出現在郵寄地址正確的郵寄地址中,「而且」無法推斷出類型的元件類型。formattedAddresspostalAddressaddressComponents 中沒有這個類型的元件。舉例來說,如果是「Boulder, Colorado, 80301, USA」的輸入值,就可能是 ['street_number', 'route']。如要查看可能的類型清單,請按這裡

unconfirmedComponentTypes[]

string

addressComponents 中顯示的元件類型,無法確認不正確。為了方便起見,這個欄位提供此欄位:其內容等同於透過 addressComponents 疊代,找出 confirmationLevel 不是 CONFIRMEDinferred 標記未設為 true 的所有元件類型。如要查看可能的類型清單,請按這裡

unresolvedTokens[]

string

輸入裝置中無法解析的任何符記。例如,系統無法識別這個輸入內容是地址的有效部分 (例如輸入如「123235253253 Main St, San Francisco, CA, 94105」這類的輸入值),則未解析的符記看起來可能像 ["123235253253"],因為這不是有效的門牌號碼。

AddressComponent

代表地址元件,例如街道、城市或州/省。

JSON 表示法
{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}
欄位
componentName

object (ComponentName)

元件的名稱。

componentType

string

地址元件的類型。如需可能的類型清單,請參閱「表 2:地點介面集服務傳回的其他類型」。

confirmationLevel

enum (ConfirmationLevel)

表示我們確定元件正確無誤。

inferred

boolean

表示輸入元件並非輸入內容的一部分,但我們根據地址位置推論此元件,且認為應提供完整的地址。

spellCorrected

boolean

表示元件名稱中拼字有誤的修正。API 不一定會將拼字變體的不同變更標記出來,例如將「centre」變更為「center」時。這項功能有時也會標記常見的錯別字,例如將「Amphitheater Pkwy」變更為「Amphitheatre Pkwy」(英式開機車) 中。

replaced

boolean

表示元件名稱已由完全不同的名稱取代,例如將錯誤的郵遞區號替換成地址正確的郵遞區號。這不是外觀的變更,而是輸入元件已變更。

unexpected

boolean

表示指定區域的郵寄地址中沒有地址元件。我們只保留了因為內容為輸入內容的一部分。

ComponentName

元件名稱的包裝函式。

JSON 表示法
{
  "text": string,
  "languageCode": string
}
欄位
text

string

名稱文字。例如「5th Avenue」代表街道名稱,「1253」代表門牌號碼。

languageCode

string

BCP-47 語言代碼。如果元件名稱與語言 (例如門牌號碼) 沒有關聯,就不會顯示這個屬性。

ConfirmationLevel

確認等級的不同可能值。

列舉
CONFIRMATION_LEVEL_UNSPECIFIED 預設值。未使用這個值。
CONFIRMED 我們能夠確認這個元件確實存在,且在地址的其他部分具有意義。
UNCONFIRMED_BUT_PLAUSIBLE 無法確認這個元件,但元件可能存在。例如街道中已知有效號碼範圍中的門牌號碼,且該號碼未知數。
UNCONFIRMED_AND_SUSPICIOUS 這個元件未經確認,可能有誤。例如與地址其餘部分不符的社區。

Geocode

內含輸入地理編碼目的地的地點相關資訊。

JSON 表示法
{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}
欄位
location

object (LatLng)

輸入內容的地理編碼位置。

比起使用地址、經緯度座標或加號,更建議使用地點 ID。使用座標來規劃行車路線或計算行車路線時,一律都會與最接近這些座標的道路對齊。這類道路不一定是即將或安全地導向目的地的道路,而且可能不在房源的存取點附近。此外,執行反向地理編碼時,我們也無法保證傳回的地址會與原始地址相符。

plusCode

object (PlusCode)

location 對應的 Plus Code。

bounds

object (Viewport)

地理編碼地點的邊界。

featureSizeMeters

number

地理編碼地點的大小 (以公尺為單位)。對於地理編碼位置的粗略性,這是另一種測量方式,但是以實際大小而非語意含義。

placeId

string

此輸入地理編碼目的地地點的 PlaceID。

如要進一步瞭解地點 ID,請參閱這篇文章

placeTypes[]

string

輸入進行地理編碼的地點類型。例如:['locality', 'political']。相關類型的完整清單請參閱這裡

LatLng

代表經緯度組合的物件。以一對雙精準數表示經度度數和緯度度數。除非另有指定,否則這個物件必須符合 WGS84 標準。此外,值必須在正規化範圍內。

JSON 表示法
{
  "latitude": number,
  "longitude": number
}
欄位
latitude

number

緯度度數,必須介於 [-90.0, +90.0] 的範圍之間。

longitude

number

經度度數,必須介於 [-180.0, +180.0] 的範圍之間。

PlusCode

Plus code (http://plus.codes) 是一種位置參照,格式有兩種:定義 14mx14m (度數 1/8000 度) 或小矩形代碼,以及複合代碼,將前置字串替換為參考位置。

JSON 表示法
{
  "globalCode": string,
  "compoundCode": string
}
欄位
globalCode

string

地點的全球 (完整) 代碼,例如「9FWM33GV+HQ」,代表 1/8000 x 1/8000 度角 (約 14 x 14 公尺)。

compoundCode

string

地點的複合代碼 (例如「33GV+HQ, Ramberg, Norway」) 包含全域代碼後置字串,並將前置字串替換成參照實體的格式化名稱。

可視區域

經緯度可視區域,以 lowhigh 點對角的對角線表示。可視區域即為封閉區域,也就是包含邊界的區域。緯度邊界必須介於 -90 到 90 度 (含首尾),經度邊界則必須介於 -180 到 180 度 (含首尾)。各種情況包括:

  • 如果 low = high,可視區域是由該單一點組成。

  • 如果 low.longitude > high.longitude,經度範圍會反轉 (可視區域與 180 度的經度線相交)。

  • 如果 low.longitude = -180 度且 high.longitude = 180 度,可視區域會包含所有經度。

  • 如果 low.longitude = 180 度,且 high.longitude = -180 度,則經度範圍是空白。

  • 如果 low.latitude > high.latitude,則緯度範圍是空白。

lowhigh 都必須填入,且代表的方塊不得空白 (如上方定義所述)。空白的可視區域會導致錯誤。

舉例來說,以下可視區域涵蓋紐約市:

{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }

JSON 表示法
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
欄位
low

object (LatLng)

必要欄位。可視區域的低點。

high

object (LatLng)

必要欄位。可視區域的高點。

AddressMetadata

地址的中繼資料。我們不保證會針對傳送至 Address Validation API 的每個地址填入 metadata

JSON 表示法
{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}
欄位
business

boolean

表示這是商家的地址。如未設定,則表示值不明。

poBox

boolean

表示郵政信箱的地址。如未設定,則表示值不明。

residential

boolean

表示這是居住地址。如未設定,則表示值不明。

UspsData

地址的 USPS 資料。我們不保證會為每個傳送至 Address Validation API 的美國或 PR 位址完整填入 uspsData。如果您使用 uspsData 做為回應的主要部分,建議您在回應中整合備用地址欄位。

JSON 表示法
{
  "standardizedAddress": {
    object (UspsAddress)
  },
  "deliveryPointCode": string,
  "deliveryPointCheckDigit": string,
  "dpvConfirmation": string,
  "dpvFootnote": string,
  "dpvCmra": string,
  "dpvVacant": string,
  "dpvNoStat": string,
  "dpvNoStatReasonCode": integer,
  "dpvDrop": string,
  "dpvThrowback": string,
  "dpvNonDeliveryDays": string,
  "dpvNonDeliveryDaysValues": integer,
  "dpvNoSecureLocation": string,
  "dpvPbsa": string,
  "dpvDoorNotAccessible": string,
  "dpvEnhancedDeliveryCode": string,
  "carrierRoute": string,
  "carrierRouteIndicator": string,
  "ewsNoMatch": boolean,
  "postOfficeCity": string,
  "postOfficeState": string,
  "abbreviatedCity": string,
  "fipsCountyCode": string,
  "county": string,
  "elotNumber": string,
  "elotFlag": string,
  "lacsLinkReturnCode": string,
  "lacsLinkIndicator": string,
  "poBoxOnlyPostalCode": boolean,
  "suitelinkFootnote": string,
  "pmbDesignator": string,
  "pmbNumber": string,
  "addressRecordType": string,
  "defaultAddress": boolean,
  "errorMessage": string,
  "cassProcessed": boolean
}
欄位
standardizedAddress

object (UspsAddress)

USPS 標準化位址。

deliveryPointCode

string

2 位數寄送點代碼

deliveryPointCheckDigit

string

寄送點檢查碼。這個號碼會加入用於自動掃描郵件,在 Delivery_point_barcode 末端所加上的號碼。將 delivery_point_barcode、deliveryPointCheckDigit、郵遞區號和 ZIP+4 的所有數字加在一起時,將得到可以用 10 除盡的數字。

dpvConfirmation

string

DPV 確認要求的可能值。會傳回單一字元或未傳回任何值。

  • N:無法透過 DPV 確認主要和任何次要號碼資訊。
  • D:系統僅針對主要號碼進行 DPV 確認,但缺少次要號碼資訊。
  • S:系統僅針對主要號碼進行 DPV 確認,其中含有次要號碼資訊,但尚未確認。
  • Y:主要和任何次要號碼的 DPV 地址已確認。
  • 空白:如果回應不含 dpvConfirmation 值,就表示沒有地址進行 DPV 確認。
dpvFootnote

string

運送點驗證的註腳。多個註腳可能會出現在同一個字串中。

  • AA:輸入地址與 ZIP+4 檔案相符
  • A1:輸入地址與 ZIP+4 檔案不符
  • BB:與 DPV (所有元件) 相符
  • CC:次要號碼不相符,非必要
  • C1:次要號碼不相符,但為必填
  • N1:高層地址缺少次要號碼
  • M1:缺少主要電話號碼
  • M3:主要號碼無效
  • P1:缺少輸入地址訂購單、RR 或說明中心方塊號碼
  • P3:輸入地址訂購單、RR 或 HC Box 號碼無效
  • F1:輸入地址與軍事地址相符
  • G1:輸入的地址與一般寄送地址相符
  • U1:輸入地址與不重複的郵遞區號相符
  • PB:輸入地址與 PBSA 記錄相符
  • RR:DPV 已確認地址,包含 PMB 資訊
  • R1:DPV 已確認地址,但未提供 PMB 資訊
  • R7:電信業者路線 R777 或 R779 記錄
  • IA:已確認電子郵件地址
  • TA:因捨棄 Alpha 版測試而比對的主要數字
dpvCmra

string

指出地址是否為 CMRA (商用郵件接收代理商),這是供客戶接收郵件的私人企業。傳回單一字元。

  • Y:地址為 CMRA
  • N:地址不是 CMRA
dpvVacant

string

這裡不開放嗎?傳回單一字元。

  • Y:地址無效
  • N:地址不是空的
dpvNoStat

string

這是否為沒有統計資料的地址或有效的地址?沒有統計資料地址,即非持續佔據的地址或 USPS 不提供服務的位址。傳回單一字元。

  • Y:網址無效
  • N:地址有效
dpvNoStatReasonCode

integer

表示 NoStat 類型。以 int 傳回原因代碼。

  • 1:IDA (內部投遞地址) – 這些地址並未直接從 USPS 接收郵件,但會寄送至負責服務的地址放置地址。
  • 2:CDS - 尚未送達的地址。舉例來說,假設有一個新的子產品群組已經確定車牌和主號碼,但還沒有可住人數的建築結構。
  • 3:碰撞 - 實際上並未由 DPV 確認的地址。
  • 4:CMZ (大專院校、軍事和其他類型) - ZIP + 4 記錄 USPS 已納入資料中。
  • 5:一般 - 表示地址未送達,且系統不會將地址計為可能的傳送作業。
  • 6:次要地址 - 此地址需要次要資訊。
dpvDrop

string

這個標記表示郵件已傳送至某個網站上單一可接收的郵件。傳回單一字元。

  • Y:郵件會傳送至網站的單一可接收郵件。
  • N:郵件未傳送到網站的單一可接收端。
dpvThrowback

string

表示郵件未傳送至街道地址。傳回單一字元。

  • Y:郵件未傳送至街道地址。
  • N:郵件會傳送至街道地址。
dpvNonDeliveryDays

string

這個標記表示郵件未在同一週內每天傳送。傳回單一字元。

  • Y:郵件不會在一週內每天送達。
  • N:沒有指出郵件會在一週內每天傳送。
dpvNonDeliveryDaysValues

integer

識別未送達天數的整數。可以使用位元旗標進行審核:0x40 - 星期日是非放送日 0x20 – 星期一是 0x08 未放送日。星期三是非放送日 0x04 – 星期三是非放送日 0x04 – 星期四是非放送日 0x02 – 星期四是非放送日。

dpvNoSecureLocation

string

這個標記表示門外有無障礙,但出於安全考量,系統不會留下包裹。傳回單一字元。

  • Y:基於安全考量,系統不會保留這個套件。
  • N:沒有任何跡象表示基於安全考量,不會留下套件。
dpvPbsa

string

表示地址與 PBSA 記錄相符。傳回單一字元。

  • Y:地址與 PBSA 記錄相符。
  • N:地址與 PBSA 記錄不相符。
dpvDoorNotAccessible

string

旗標用於表示 USPS 無法親自寄門郵件的地址。傳回單一字元。

  • Y:無法存取門。
  • N:沒有表示無法存取門。
dpvEnhancedDeliveryCode

string

表示地址的有效 DPV 傳回代碼。傳回單一字元。

  • Y:主要和任何次要號碼的 DPV 地址已確認。
  • N:無法透過 DPV 確認主要和任何次要號碼資訊。
  • S:系統僅針對主要號碼進行 DPV 確認,且未確認次要號碼資訊顯示了次要號碼資訊,或是捨棄主要號碼的結尾 Alpha 版,以達到 DPV 比對和次要資訊的要求。
  • D:系統僅針對主要號碼進行 DPV 確認,但缺少次要號碼資訊。
  • R:地址已確認,但已獲派路徑 R777 和 R779,且未提供 USPS 傳送功能。
carrierRoute

string

貨運公司路線代碼。由 1 個字母前置字元和 3 位數路線指示器所組成的四個字元代碼。

前置字串:

  • C:貨運公司路線 (或城市道路)
  • R:鄉村路線
  • H:高速公路合約路線
  • B:郵政信箱區段
  • G:一般放送單位
carrierRouteIndicator

string

貨運公司路線費率排序指標。

ewsNoMatch

boolean

寄送地址可以比對,不過 EWS 檔案表示很快就會取得完全相符的地址。

postOfficeCity

string

主要郵局城市。

postOfficeState

string

主要的郵局狀態。

abbreviatedCity

string

縮寫城市。

fipsCountyCode

string

FIPS 縣市代碼。

county

string

郡/縣名稱。

elotNumber

string

加強行業 (eLOT) 編號。

elotFlag

string

eLOT 遞增/遞減標記 (A/D)。

poBoxOnlyPostalCode

boolean

郵政信箱僅包含郵遞區號。

pmbDesignator

string

PMB (私人信箱) 單元設計人員。

pmbNumber

string

PMB (私人信箱) 號碼;

addressRecordType

string

與輸入地址相符的地址記錄類型。

  • F:FIRM。這會與「Firm Record」相符,這是針對某地址提供最精細的比對等級。
  • G:一般交付。這項資訊與一般配送記錄相符。
  • H:建立 / 交集。這個值與建築物或公寓記錄相符。
  • P:張貼方塊。這是與郵政信箱完全相符的項目。
  • R: RURAL ROUTE 或 HighWAY PASCT:與鄉村路線或高速公路合約記錄相符,兩者都可能有相關聯的裝箱編號範圍。
  • S:STREET RECORD:這是與包含有效主要號碼範圍的街景服務記錄相符的項目。
defaultAddress

boolean

這個指標代表已找到預設地址,但存在更明確的地址。

errorMessage

string

USPS 資料擷取的錯誤訊息。如果因為偵測到人工建立地址而暫停 USPS 處理作業,系統就會填入這項資訊。

發生這個錯誤時,系統可能不會填入 USPS 資料欄位。

cassProcessed

boolean

表示要求已處理 CASS 處理的指標。

UspsAddress

USPS 表示法。

JSON 表示法
{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}
欄位
firstAddressLine

string

第一行地址。

firm

string

公司名稱。

secondAddressLine

string

第二行地址

urbanization

string

波多黎各都市化名稱。

cityStateZipAddressLine

string

城市 + 州/省 + 郵遞區號。

city

string

城市名稱。

state

string

由 2 個英文字母組成的州碼。

zipCode

string

郵遞區號,例如 10009。

zipCodeExtension

string

4 位數郵遞區號額外資訊,例如 5023。