Package google.maps.addressvalidation.v1

索引

地址驗證

用於驗證地址的服務。

提供驗證意見回饋

rpc ProvideValidationFeedback(ProvideValidationFeedbackRequest) returns (ProvideValidationFeedbackResponse)

針對驗證嘗試順序結果的意見回饋。這是在對相同地址進行一連串驗證呼叫後所發出的最後呼叫，而且交易完成後應呼叫此呼叫。這項資訊只能針對完整驗證地址所需的 ValidateAddress 要求序列傳送一次。
驗證地址

rpc ValidateAddress(ValidateAddressRequest) returns (ValidateAddressResponse)

驗證地址。

地址

後處理地址的詳細資料。後續處理作業包括更正地址的拼寫錯誤、更換錯誤部分，以及推測缺漏的部分。

欄位
formatted_address

string

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

PostalAddress

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

AddressComponent

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

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

string

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

string

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

string

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

位址元件

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

欄位
component_name

ComponentName

這個元件的名稱。
component_type

string

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

ConfirmationLevel

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

bool

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

bool

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

bool

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

bool

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

確認層級

確認層級可能出現的值。

列舉
CONFIRMATION_LEVEL_UNSPECIFIED 預設值。這個值未使用。
CONFIRMED 我們得以驗證該元件確實存在，而且適用於其他地址的部分。
UNCONFIRMED_BUT_PLAUSIBLE 無法確認這個元件，但該元件可能存在。例如，無法識別特定門牌號碼的街道所列有效號碼範圍內的門牌號碼。
UNCONFIRMED_AND_SUSPICIOUS 未經確認，這個元件可能有誤。例如不適合地址其餘的社區。

位址中繼資料

地址的中繼資料。metadata 不保證每個傳送至 Address Validation API 的地址都會完整填入。

欄位
business

bool

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

bool

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

bool

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

元件名稱

元件名稱的包裝函式。

欄位
text

string

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

string

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

Geocode

包含輸入項目進行地理編碼的地點相關資訊。

欄位
location

LatLng

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

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

PlusCode

與 location 對應的加號。
bounds

Viewport

地理編碼地點的界限。
feature_size_meters

float

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

string

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

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

string

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

語言選項

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

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

欄位
return_english_latin_address

bool

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

PlusCode

Plus Code (http://plus.codes) 是一個位置參照，包含兩種格式：定義 14mx14m (度數的 1/8000) 或較小矩形的全域程式碼，以及複合代碼，將前置字元替換為參照位置。

欄位
global_code

string

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

string

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

提供驗證意見回饋要求

傳送驗證意見回饋的要求。

欄位
conclusion

ValidationConclusion

必要欄位。驗證嘗試順序的結果。

如果將這個欄位設為 VALIDATION_CONCLUSION_UNSPECIFIED，系統會傳回 INVALID_ARGUMENT 錯誤。
response_id

string

必要欄位。針對這項意見回饋的回應 ID。這應該是一系列地址驗證嘗試中第一個回應的 [response_id][google.maps.addressvalidation.v1.ValidateAddressRequest.response_id]。

驗證結論

地址驗證要求驗證地址所需的最終結果。

列舉
VALIDATION_CONCLUSION_UNSPECIFIED 這個值未使用。如果將 ProvideValidationFeedbackRequest.conclusion 欄位設為 VALIDATION_CONCLUSION_UNSPECIFIED，系統會傳回 INVALID_ARGUMENT 錯誤。
VALIDATED_VERSION_USED 用於交易的 Address Validation API 傳回的地址版本。
USER_VERSION_USED 使用者提供的交易地址版本
UNVALIDATED_VERSION_USED 上次嘗試驗證後所輸入的地址版本，但未重新驗證用於這筆交易。
UNUSED 交易已放棄，系統並未使用地址。

提供驗證意見回饋回應

這個類型沒有任何欄位。

驗證意見回饋的回應。

如果已成功傳送意見回饋，則回應會留空。

USpsAddress

USPS 代表美國的地址。

欄位
first_address_line

string

第一行地址
firm

string

公司名稱。
second_address_line

string

第二行地址。
urbanization

string

波多黎各都會區名稱。
city_state_zip_address_line

string

城市 + 州 + 郵遞區號。
city

string

城市名稱。
state

string

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

string

郵遞區號，例如 10009。
zip_code_extension

string

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

usps 資料

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

欄位
standardized_address

UspsAddress

USPS 標準化地址。
delivery_point_code

string

2 位數送貨地點代碼
delivery_point_check_digit

string

寄送點檢查碼。這個編號會加入自動掃描郵件的 Delivery_point_barcode 結尾。將 Delivery_point_barcode、delivery_point_check_ 碼、郵遞區號和 ZIP+4 等所有數字相加，即可得出可被 10 除盡的數字。
dpv_confirmation

string

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

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

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 記錄
dpv_cmra

string

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

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

string

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

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

string

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

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

string

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

前置字元：

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

string

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

bool

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

string

主要郵局城市。
post_office_state

string

主要郵局狀態。
abbreviated_city

string

縮寫城市。
fips_county_code

string

FIPS 郡/縣代碼。
county

string

郡/縣名稱。
elot_number

string

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

string

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

bool

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

string

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

string

PMB (私人信箱) 號碼；
address_record_type

string

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

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

bool

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

string

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

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

bool

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

驗證地址要求

驗證地址的要求。

欄位
address

PostalAddress

必要欄位。正在驗證的地址。未格式化的地址應透過 address_lines 提交。

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

如需支援的地區，請參閱這篇文章。

輸入位址中的 language_code 值將保留給日後使用，而且今天會忽略該值。系統會根據您指定地址的偏好語言，填入驗證的地址結果 (由系統辨識)。

Address Validation API 會忽略 recipients 和 organization 中的值。系統將捨棄這些欄位中的所有值，而不會傳回值。請勿設定。
previous_response_id

string

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

bool

啟用 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 必須以「波多黎各」(不區分大小寫) 或「PR」格式提供。

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

LanguageOptions

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

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

驗證地址回應

地址驗證要求的回應。

欄位
result

ValidationResult

地址驗證的結果。
response_id

string

用於識別此回應的 UUID。如果位址需要重新驗證，這個 UUID 必須隨新要求一起出現，

ValidationResult

地址驗證的結果。

欄位
verdict

Verdict

整體判定結果標記
address

Address

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

Geocode

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

AddressMetadata

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

UspsData

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

Address

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

地址已翻譯成英文。如果地址有部分沒有英文翻譯，服務會透過使用拉丁字母的替代語言傳回該部分。請參閱這篇文章，瞭解選取替代語言的方式。如果地址的組成部分沒有任何使用拉丁字母的語言翻譯或音譯，則服務會以與地址相關聯的當地語言傳回該部分。

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

注意：english_latin_address 的 google.maps.addressvalidation.v1.Address.unconfirmed_component_types 欄位和 english_latin_address.address_components 中的 google.maps.addressvalidation.v1.AddressComponent.confirmation_level 欄位不會填入資料。

評斷

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

欄位
input_granularity

Granularity

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

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

Granularity

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

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

Granularity

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

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

bool

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

bool

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

bool

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

bool

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

精細程度

地址或地理編碼的各種精細程度。用於表示 address 的精細程度時，這些值會指出郵件地址的精細程度。例如，「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 所有其他精細程度 (因無法交付而分為同一組)。