Method: validateAddress

{
  "revision": integer,
  "regionCode": string,
  "languageCode": string,
  "postalCode": string,
  "sortingCode": string,
  "administrativeArea": string,
  "locality": string,
  "sublocality": string,
  "addressLines": [
    string
  ],
  "recipients": [
    string
  ],
  "organization": string
}

integer

PostalAddress 的結構定義修訂版本。任何大於 0 的值都會導致 API 傳回 INVALID_ARGUMENT 錯誤。

string

(選填) 地址所在國家/地區的 CLDR 地區代碼。詳情請參閱 https://cldr.unicode.org/ 和 https://www.unicode.org/cldr/charts/30/companion/area_information.html。例如：「CH」代表瑞士。如果沒有提供區碼，系統會從地址推斷出。為獲得最佳效能，建議您加入區域代碼 (如果知道的話)。使用不一致或重複的區域可能會導致效能不佳，例如，如果 addressLines 已包含區域，請勿在這個欄位中再次提供區碼。如需支援的地區，請參閱常見問題。

string

輸入地址中的語言代碼會保留給日後使用，系統今天會忽略該語言代碼。API 會以適當的語言傳回地址所在的地址。

string

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

string

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

string

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

string

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

string

(選填) 地址的縣市以下行政區，例如社區、自治市鎮和區等。

string

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

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

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

如要處理完全非結構化的地址，建議你建立僅包含 addressLines 的地址，並使用地理編碼，因為這樣就不必猜測地址的哪些部分應為縣市或行政區。

string

請勿設定這個欄位。Address Validation API 目前未使用。雖然目前 API 不會拒絕設定這個欄位的要求，但系統會捨棄資訊，也不會透過回應傳回。

string

請勿設定這個欄位。Address Validation API 目前未使用。雖然目前 API 不會拒絕設定這個欄位的要求，但系統會捨棄資訊，也不會透過回應傳回。

{
  "returnEnglishLatinAddress": boolean
}

boolean

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

{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  },
  "englishLatinAddress": {
    object (Address)
  }
}

object (Verdict)

整體判定結果標記

object (Address)

地址本身的相關資訊，而不是地理編碼。

object (Geocode)

地址的地理編碼地點和地點相關資訊。

object (AddressMetadata)

與貨品交付相關的其他資訊。metadata 不保證每個傳送至 Address Validation API 的地址都會完整填入。

object (UspsData)

USPS 提供的其他可交付標記。只在區域 US 和 PR 提供。

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 欄位不會填入資料。

{
  "inputGranularity": enum (Granularity),
  "validationGranularity": enum (Granularity),
  "geocodeGranularity": enum (Granularity),
  "addressComplete": boolean,
  "hasUnconfirmedComponents": boolean,
  "hasInferredComponents": boolean,
  "hasReplacedComponents": boolean
}

enum (Granularity)

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

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

enum (Granularity)

API 可完整驗證位址的精細程度。舉例來說，PREMISE 的 validationGranularity 表示 PREMISE 層級或更粗略層級的所有地址元件都可以驗證。

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

enum (Granularity)

geocode 精細程度的相關資訊。我們可以理解這是地理編碼位置的語意含義。

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

boolean

如果沒有未解析的權杖、沒有未解析或遺漏的地址元件，系統會將位址視為完整。詳情請參閱 missingComponentTypes、unresolvedTokens 或 unexpected 欄位。

boolean

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

boolean

系統推測 (新增) 至少一個不在輸入中的地址元件，詳情請參閱 google.maps.addressvalidation.v1.Address.address_components。

boolean

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

{
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "addressComponents": [
    {
      object (AddressComponent)
    }
  ],
  "missingComponentTypes": [
    string
  ],
  "unconfirmedComponentTypes": [
    string
  ],
  "unresolvedTokens": [
    string
  ]
}

string

經過處理的地址，格式為單行地址，符合該地址所在地區的地址格式設定規則。

object (PostalAddress)

經過後處理的地址，表示為郵寄地址。

object (AddressComponent)

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

地址元件沒有以特定方式排序。請勿假設清單中地址元件的排序方式。

string

預期格式正確的郵寄地址中應會顯示的元件類型，而且輸入中「而且」無法推論出這些元件類型。此類型的元件不會顯示在 formattedAddress、postalAddress 或 addressComponents 中。例如，例如「Boulder, Colorado, 80301, USA」等輸入內容，可以是 ['street_number', 'route']。如要查看可能的類型清單，請前往這裡。

string

addressComponents 中顯示的元件類型，我們無法確認其類型是否正確。為了方便起見，這個欄位提供：其內容等同於疊代 addressComponents 來找出所有元件類型，其中 confirmationLevel 不是 CONFIRMED 或 inferred 標記未設為 true。如要查看可能的類型清單，請前往這裡。

string

輸入內容中的所有權杖均無法解析。這可能不是地址的有效部分 (例如在輸入「123235253253 Main St, San Francisco, CA, 94105」的輸入內容中，未解析的符記可能是 ["123235253253"]，因為這類代碼不是有效的門牌號碼)。

{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}

object (ComponentName)

這個元件的名稱。

string

地址元件的類型。請參閱表 2：地點介面集服務傳回的其他類型，取得可能的類型清單。

enum (ConfirmationLevel)

表示我們擁有元件正確的確定程度。

boolean

表示此元件並非輸入部分的一部分，但我們從地址位置推測得出這個元件，並認為該元件應提供完整的地址。

boolean

表示元件名稱拼寫錯誤的修正內容。API 不一定會標記拼寫錯誤的不同版本 (例如將「centre」變更為「center」)。此外，系統不一定會標記常見的錯別字，例如將「Amphitheater Pkwy」改為「Amphitheatre Pkwy」就對了。

boolean

表示元件名稱已替換為完全不同的名稱，例如將郵遞區號替換成地址正確的郵遞區號。這不是外觀變更，系統已將輸入元件變更為其他元件。

boolean

代表不應出現在指定區域的郵寄地址中。不過，我們只保留該段資料，因為這是輸入內容的一部分。

{
  "text": string,
  "languageCode": string
}

string

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

string

BCP-47 語言代碼。如果元件名稱與語言 (例如門牌號碼) 沒有關聯，就不會顯示出來。

{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}

object (LatLng)

輸入項目的地理編碼位置。

相較於使用地址、經緯度座標或加號代碼，就偏好使用地點 ID。在路線規劃或計算行車路線時使用座標，系統一律會將點對齊至最接近這些座標的道路。這條道路不一定要快速或安全引導至目的地，也不得鄰近房源的存取點。此外，即使位置經過反向地理編碼，我們也無法保證傳回的地址會與原始地址相符。

object (PlusCode)

與 location 對應的加號。

object (Viewport)

地理編碼地點的界限。

number

地理編碼地點的大小 (以公尺為單位)。這是另一個測量地理編碼位置的概略度，但實際上是實際大小，而非語意含義。

string

此輸入內容的地理編碼地點 PlaceID。

如要進一步瞭解地點 ID，請參閱本文。

string

輸入地點的地理編碼地點類型，例如：['locality', 'political']。如需完整的類型清單，請前往這裡。

{
  "latitude": number,
  "longitude": number
}

number

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

number

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

{
  "globalCode": string,
  "compoundCode": string
}

string

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

string

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

{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}

object (LatLng)

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

object (LatLng)

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

{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}

boolean

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

boolean

指出郵政信箱的地址。如未設定，表示該值不明。

boolean

表示這是居住的地址。如未設定，表示該值不明。

{
  "standardizedAddress": {
    object (UspsAddress)
  },
  "deliveryPointCode": string,
  "deliveryPointCheckDigit": string,
  "dpvConfirmation": string,
  "dpvFootnote": string,
  "dpvCmra": string,
  "dpvVacant": string,
  "dpvNoStat": 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
}

object (UspsAddress)

USPS 標準化地址。

string

2 位數送貨地點代碼

string

寄送點檢查碼。這個編號會加入自動掃描郵件的 Delivery_point_barcode 結尾。將 Delivery_point_barcode、deliveryPointCheckDigit、郵遞區號和 ZIP+4 的數字都相加，應該可得出 10 除以 10 的數字。

string

DPV 確認值可能的值。傳回單一字元。

• Y：已確認主要和任何次要號碼的 DPV。
• N：主要和任何次要號碼資訊無法確認 DPV。
• S：僅有主要號碼的 DPV 確認地址，且次要號碼資訊存在但未確認。
• D：只確認了主要電話號碼的 DPV，缺少次要號碼資訊。

string

交貨地點驗證資訊中的註腳。同一個字串中可能會有多個註腳。

• AA：輸入的地址與 ZIP+4 檔案相符
• A1：輸入的地址與 ZIP+4 檔案不符
• BB：與 DPV (所有元件) 相符
• CC：次要號碼不相符 (顯示，但無效)
• N1：高樓層地址缺少次要號碼
• M1：缺少主要編號
• M3：主要號碼無效
• P1：缺少輸入地址 RR 或說明中心方塊編號
• P3：輸入地址的 PO、RR 或說明中心方塊號碼無效
• F1：輸入的地址符合軍事地址
• G1：輸入至一般寄送地址的地址
• U1：輸入的地址對應至專屬郵遞區號
• PB：輸入的地址與 PBSA 記錄相符
• RR：DPV 已確認地址 (含有 PMB 資訊)
• R1：DPV 已確認地址，不含 PMB 資訊
• R7：電信業者路徑 R777 或 R779 記錄

string

用於表示地址是否為 CMRA (商業郵件接收機構)，這是為客戶接收郵件的私人企業。傳回單一字元。

• Y：地址是 CMRA
• N：地址不是 CMRA

string

這裡不吃嗎？傳回單一字元。

• Y：地址是空的
• N：地址不是空

string

這裡不是統計資料，還是使用中的地址？沒有任何統計資料地址是非持續使用的地址，或 USPS 不提供服務的地址。傳回單一字元。

• Y：地址無效
• N：地址已啟用

string

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

前置字元：

• C：貨運公司路線 (或城市道路)
• R：鄉村路線
• H：公路合約路線
• B：郵政信箱部分
• G：一般放送單位

string

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

boolean

寄送地址可以一致，但 EWS 檔案表示即將提供完全相符的相符地址。

string

主要郵局城市。

string

主要郵局狀態。

string

縮寫城市。

string

FIPS 郡/縣代碼。

string

郡/縣名稱。

string

進階旅遊路線 (eLOT) 號碼。

string

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

string

LACSLink 傳回代碼。

string

LACSLink 指標。

boolean

僅限郵政信箱的郵遞區號。

string

比對街道、高樓記錄和套房資訊的註腳。如果找到相符的商家名稱，就會傳回次要號碼。

• A：套件記錄相符，已改善商家地址。
• 00：不會相符，因此商家地址未經改善。

string

PMB (私人信箱) 單位設計器。

string

PMB (私人信箱) 號碼；

string

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

• F：FIRM。這等同於與公司記錄進行比對，此記錄是特定地址可用的最精確比對層級。
• G：一般放送。這個記錄與一般運送記錄相符。
• H：建立 / 組成。這項資訊與建築物或公寓記錄相符。
• P：張貼離線盒。這個文件與郵政信箱相符。
• R： RURAL ROUTE 或 HIGHWAY CONTRACT：與鄉村路線或高速公路合約記錄相符，兩者都有可能相關聯的「盒牌編號」範圍。
• S：STREET RECORD：這與包含有效主要數字範圍的街道記錄相符。

boolean

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

string

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

出現這個錯誤時，系統可能不會填入 USPS 資料欄位。

boolean

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

{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}

string

第一行地址

string

公司名稱。

string

第二行地址。

string

波多黎各都會區名稱。

string

城市 + 州 + 郵遞區號。

string

城市名稱。

string

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

string

郵遞區號，例如 10009。

string

4 位數郵遞區號延伸，例如 5023。