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 會忽略 recipients 和 organization 中的值。系統會捨棄這些欄位中的所有值，不會傳回。請勿設定。
previousResponseId

string

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

boolean

啟用 USPS CASS 相容模式。這項變更只會影響 google.maps.addressvalidation.v1.ValidationResult 的 google.maps.addressvalidation.v1.ValidationResult.usps_data 欄位。注意：如果是針對波多黎各地址提出的 USPS CASS 啟用要求，address 的 google.type.PostalAddress.region_code 必須提供為「PR」，或是 address 的 google.type.PostalAddress.administrative_area 必須提供為「Puerto Rico」(不區分大小寫) 或「PR」。

建議您使用元件化 address，或者至少指定兩個 google.type.PostalAddress.address_lines，第一行包含門牌號碼和名稱，第二行則包含城市、州和郵遞區號。
languageOptions

object (LanguageOptions)

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

讓 Address Validation API 在回應中加入其他資訊。
sessionToken

string

(選用步驟) 用於計費的 Autocomplete 工作階段識別字串。必須是安全的 base64 字串，且長度不得超過 36 個 ASCII 字元。否則會傳回 INVALID_ARGUMENT 錯誤。

工作階段會在使用者提出自動完成查詢時開始，並在使用者選取地點並發出對地點詳細資料或地址驗證的呼叫時結束。在每個工作階段中，使用者可以輸入多筆 Autocomplete 查詢，最終選擇一個 Place Details 或 Address Validation 要求。在單一工作階段中，每項要求使用的憑證都必須屬於同一個 Google Cloud 控制台專案。工作階段結束後，符記就會失效；您的應用程式必須為每個工作階段產生新的符記。如果省略 sessionToken 參數或重複使用工作階段符記，系統會視為未提供工作階段符記，並針對工作階段收費 (每個要求分別收費)。

注意：Address Validation 只能用於使用 Autocomplete (新版) 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)

其他與可送達性相關的資訊。metadata 不保證會為傳送至 Address Validation API 的每個地址完整填入資料。
uspsData

object (UspsData)

美國郵政署提供的額外送達標記。僅在 US 和 PR 地區提供。
englishLatinAddress

object (Address)

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

已翻譯成英文的地址。

翻譯的地址無法用於 API 輸入。服務會提供這些選項，方便使用者以母語確認或否認原先提供的地址是否有效。

如果部分地址沒有英文翻譯，服務會以使用拉丁字母的其他語言傳回該部分。如要瞭解系統如何選取替代語言，請參閱這篇文章。如果部分地址沒有使用拉丁字母的語言翻譯或轉寫，服務會以與地址相關聯的當地語言傳回該部分。

使用 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,
  "possibleNextAction": enum (PossibleNextAction),
  "hasSpellCorrectedComponents": boolean
}
欄位
inputGranularity

enum (Granularity)

輸入地址的精細程度。這是剖析輸入地址的結果，不會提供任何驗證信號。如需驗證信號，請參閱下方的 validationGranularity。

舉例來說，如果輸入的地址包含特定公寓號碼，這裡的 inputGranularity 就會是 SUB_PREMISE。如果地址驗證服務無法比對資料庫中的公寓號碼，或是公寓號碼無效，validationGranularity 可能會是 PREMISE 或更粗略。
validationGranularity

enum (Granularity)

API 可完全驗證的後處理地址精細程度。舉例來說，如果 validationGranularity 為 PREMISE，表示所有地址元件 (PREMISE 等級或更粗略的等級) 皆可驗證。

您可以在 google.maps.addressvalidation.v1.Address.address_components 中查看每個地址元件的驗證結果。
geocodeGranularity

enum (Granularity)

geocode 的精細程度資訊。這可視為地理編碼位置的語意意義，表示地點的精確程度。

這可能與上述 validationGranularity 不同。舉例來說，我們的資料庫可能會記錄公寓號碼，但沒有公寓在大型公寓大廈內的確切位置。在這種情況下，validationGranularity 會是 SUB_PREMISE，但 geocodeGranularity 會是 PREMISE。
addressComplete

boolean

如果後處理的地址沒有未解析的符記，且沒有意外或缺少的地址元件，則系統會將該地址視為完整。如果未設定，表示值為 false。詳情請參閱 missingComponentTypes、unresolvedTokens 或 unexpected 欄位。
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。
possibleNextAction

enum (PossibleNextAction)

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

提供 API 回應的解釋摘要，協助判斷後續可能採取的行動。這個欄位是從 API 回應中的其他欄位衍生而來，不應視為地址準確度或可送達性的保證。詳情請參閱「建構驗證邏輯」。
hasSpellCorrectedComponents

boolean

至少有一個地址元件經過拼字校正，詳情請參閱 google.maps.addressvalidation.v1.Address.address_components。

精細程度

地址或地理編碼可具有的各種精細程度。當用於表示地址的精細程度時，這些值會指出地址如何識別郵寄目的地的精細程度。舉例來說，「123 Main Street, Redwood City, CA, 94061」這類地址會識別 PREMISE，而「Redwood City, CA, 94061」這類地址則會識別 LOCALITY。不過，如果我們找不到位於 Redwood City 的「123 Main Street」地理編碼，則系統可能會傳回 LOCALITY 精細度的地理編碼，即使地址精細度更高也一樣。

列舉
GRANULARITY_UNSPECIFIED 預設值。此值未使用。
SUB_PREMISE 建築物以下的結果，例如公寓。
PREMISE 建築物層級結果。
PREMISE_PROXIMITY 大致對應地址的建築物層級位置。
BLOCK 地址或地理編碼代表街區。僅用於有區塊層級位址的地區，例如日本。
ROUTE 地理編碼或地址是精細的路線，例如街道、道路或高速公路。
OTHER 所有其他精細度 (由於無法傳送，因此會歸入同一類別)。

PossibleNextAction

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

根據 API 回應，可能採取的後續行動。

列舉
POSSIBLE_NEXT_ACTION_UNSPECIFIED 預設值。此值未使用。
FIX API 回應中有一或多個欄位指出後處理地址可能有問題，例如 verdict.validation_granularity 是 OTHER。提醒顧客編輯地址，有助於提升地址品質。
CONFIRM_ADD_SUBPREMISES API 回應指出經後處理的地址可能缺少子門牌。請顧客確認地址，並考慮加入單元號碼，有助於改善地址品質。經後處理的地址也可能有其他小問題。注意：這個列舉值只能針對美國地址傳回。
CONFIRM API 回應中有一或多個欄位指出後處理地址可能有小問題，例如 postalCode 地址元件為 replaced。請客戶確認地址，有助於改善地址品質。
ACCEPT API 回應不含可保證其他 PossibleNextAction 值的訊號。您可以考慮使用經後處理的地址，而無須進一步提示客戶，但這並不能保證地址有效，且地址可能仍包含修正項目。您有責任根據自身的風險評估，決定是否要向客戶顯示提示，以及提示的方式。

地址

後處理地址的詳細資料。後置處理包括修正地址中拼錯的部分、取代不正確的部分，以及推斷遺漏的部分。

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

string

經過後續處理的地址，格式為單行地址，並遵循地址所在區域的地址格式規則。

注意：此地址的格式可能與 postalAddress 欄位中的地址格式不符。舉例來說，postalAddress 一律會以 2 個字母 regionCode 表示國家/地區，例如「US」或「NZ」。相較之下，這個欄位會使用較長的國家/地區名稱，例如「USA」或「New Zealand」。
postalAddress

object (PostalAddress)

經後處理的地址，以郵寄地址表示。
addressComponents[]

object (AddressComponent)

未排序的清單。經過格式修正的地址，以及驗證資訊。這項資訊可提供個別元件的驗證狀態。

地址元件並未依特定順序排列。請勿對清單中地址元件的順序做出任何假設。
missingComponentTypes[]

string

在正確格式的郵寄地址中，預期會出現的元件類型，但在輸入內容中找不到，也無法推斷。例如，如果輸入「Boulder, Colorado, 80301, USA」這類資訊，就會顯示 ['street_number', 'route']。如要查看可能的類型清單，請按這裡。

注意：當您認為已提供缺少的元件時，可能會看到缺少的元件類型。舉例來說，如果輸入的地址包含大樓名稱，但沒有門牌號碼，就可能會發生這種情況。在「渋谷区渋谷３丁目　 Shibuya Stream」這個地址中，大樓名稱「Shibuya Stream」的元件類型為 premise，但缺少房號，因此 missingComponentTypes 會包含 premise。
unconfirmedComponentTypes[]

string

addressComponents 中出現的元件類型，但無法確認其正確性。這個欄位是為了方便使用者：其內容等同於透過 addressComponents 迴圈，找出 confirmationLevel 不是 CONFIRMED 或 inferred 標記未設為 true 的所有元件類型。如要查看可能的類型清單，請按這裡。
unresolvedTokens[]

string

輸入內容中無法解析的任何符記。這可能是系統無法辨識為有效地址的輸入內容。舉例來說，如果輸入的內容是「Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US」，未解析的符記可能會是 ["Parcel", "0000123123", "&", "0000456456"]。

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，而非地址、經緯度座標或 Plus Code。在規劃路線或計算行車路線時使用座標，系統一律會將點對齊最接近該座標的道路。這條路可能無法快速或安全地通往目的地，也可能不在房源附近。此外，當位置經過反向地理編碼後，我們無法保證傳回的地址會與原始地址相符。
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) 是一種位置參照，有兩種格式：全球代碼定義 14 公尺 x 14 公尺 (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」，包含全球代碼的後置字串，並將前置字串替換為參考實體的格式化名稱。

可視區域

經緯度可視區域，以兩個對角相反的 low 和 high 點表示。可視區域視為封閉區域，也就是包含邊界。緯度範圍必須介於 -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，則經度範圍為空白。

low 和 high 都必須填入資料，且代表的方塊不得為空白 (如上述定義所述)。空白的檢視區會導致錯誤。

舉例來說，這個檢視區會完全包含紐約市：

{ "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

經後製處理的地址的中繼資料。metadata 不保證會為傳送至 Address Validation API 的每個地址完整填入資料。

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

boolean

表示這是商家地址。如果未設定，表示值不明。
poBox

boolean

表示郵政信箱的地址。如果未設定，表示值不明。
residential

boolean

表示這是住家地址。如果未設定，表示值不明。

UspsData

地址的 USPS 資料。uspsData 不保證會為每個傳送至 Address Validation API 的美國或波多黎各地址完整填入資料。如果您將 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、郵遞區號和郵遞區號 + 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：輸入地址時缺少郵政信箱、郵局信箱或郵局信箱號碼
  • P3：輸入的地址 PO、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 (大學、軍事和其他類型) - 美國郵政署已納入資料的郵遞區編號 + 4 記錄。
  • 5：一般 - 表示地址未收到郵件，且這些地址不會計入可能送達的郵件。
  • 6：需要次要資訊 - 地址需要次要資訊。
dpvDrop

string

標記表示郵件已傳送至網站上的單一收件匣。傳回單一字元。

  • Y：郵件會送至網站上的單一收件匣。
  • N：郵件並未送達網站上的單一收件者。
dpvThrowback

string

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

  • Y：郵件未送達街道地址。
  • N：郵件會送到街道地址。
dpvNonDeliveryDays

string

此標記表示郵件並非在每週的每一天送達。傳回單一字元。

  • Y：郵件並非每週的每一天都會送達。
  • N：沒有郵件傳送時間表，無法確認郵件並非每週的每一天都會送達。
dpvNonDeliveryDaysValues

integer

整數，用於識別未放送日。您可以使用位元旗標進行查詢：0x40 – 週日為非送達日 0x20 – 週一為非送達日 0x10 – 週二為非送達日 0x08 – 週三為非送達日 0x04 – 週四為非送達日 0x02 – 週五為非送達日 0x01 – 週六為非送達日
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 比對，次要號碼資訊雖然存在但未經確認，或是主要號碼的單一尾碼遭到刪除，導致 DPV 比對失敗，因此需要次要資訊。
  • D：地址僅針對主要號碼通過 DPV 驗證，且缺少次要號碼資訊。
  • R：地址已確認，但指派給虛設路線 R777 和 R779，且未提供 USPS 運送服務。
carrierRoute

string

運送公司路線代碼。四個字元的代碼，包含一個英文字母前置字串和三位數路線標記。

前置字串：

  • 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 (Private Mail Box) 單位指標。
pmbNumber

string

PMB (Private Mail Box) 號碼
addressRecordType

string

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

  • F：FIRM。這是與「確實記錄」的比對結果，這是地址可用的最精確比對結果。
  • G：一般運送。這項資訊與一般寄送記錄相符。
  • H：建築物 / 公寓。這項資料與「建築物」或「公寓」記錄相符。
  • P：郵政信箱。這是與郵政信箱的比對結果。
  • R：RURAL ROUTE 或 HIGHWAY CONTRACT：這項屬性會與 Rural Route 或 Highway Contract 記錄相符，兩者都可能有相關聯的 Box Number 範圍。
  • S：街道記錄：這是與街道記錄相符，其中包含有效的主要號碼範圍。
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。