Package google.maps.addressvalidation.v1

索引

AddressValidation

用於驗證地址的服務。

ProvideValidationFeedback

rpc ProvideValidationFeedback(ProvideValidationFeedbackRequest) returns (ProvideValidationFeedbackResponse)

有關嘗試驗證序列結果的意見回饋。這應該是同一個地址依序發出驗證呼叫後的最後一個呼叫,且應在交易完成後呼叫。這一系列 ValidateAddress 要求只需針對完整驗證地址所需的一系列要求傳送一次。

ValidateAddress

rpc ValidateAddress(ValidateAddressRequest) returns (ValidateAddressResponse)

驗證地址。

地址

後續處理地址的詳細資料。後續處理作業包括更正地址中錯字、替換錯誤部分以及推斷缺失的部分。

欄位
formatted_address

string

按照地址所在區域的地址格式規則,採取後續處理的地址格式,格式為單行地址。

postal_address

PostalAddress

以郵政地址表示的後續處理地址。

address_components[]

AddressComponent

未排序的清單。格式化地址和修正後地址的個別地址元件,以及驗證資訊。這項資訊會提供個別元件的驗證狀態資訊。

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

missing_component_types[]

string

預期出現在正確格式郵寄地址、但輸入中,「以及」無法推論的元件類型。formatted_addresspostal_addressaddress_components 中沒有這個類型的元件。舉例來說,「Boulder, Colorado, 80301, USA」等輸入內容,可能會是 ['street_number', 'route']。您可以在這裡查看可能類型的清單。

unconfirmed_component_types[]

string

存在於 address_components 中,但無法確認的元件類型。為方便起見,我們提供了這個欄位:其內容等同於透過 address_components 疊代,找出 confirmation_level 不是 CONFIRMEDinferred 旗標未設為 true 的所有元件類型。您可以在這裡查看可能類型的清單。

unresolved_tokens[]

string

輸入資料中有任何無法解析的權杖。這可能表示輸入的地址並非有效地址部分 (例如在「123235253253 Main St, San Francisco, CA, 94105」等輸入內容中,未解析的權杖看起來可能像 ["123235253253"],因為這看起來不像有效的門牌號碼)。

AddressComponent

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

欄位
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

表示特定區域的郵寄地址中,不應出現的地址元件。我們只保留了這個字,因為它是輸入內容的一部分。

ConfirmationLevel

確認層級的不同可能值。

列舉
CONFIRMATION_LEVEL_UNSPECIFIED 預設值。這個值未使用。
CONFIRMED 我們可驗證該元件是否存在,且與地址的其他內容一致。
UNCONFIRMED_BUT_PLAUSIBLE 無法確認這個元件,但有可能存在。例如路上已知有效號碼範圍內的門牌號碼,但系統無法識別特定門牌號碼。
UNCONFIRMED_AND_SUSPICIOUS 這個元件未經確認,可能有誤。例如與地址其餘部分不符的社區。

AddressMetadata

位址的中繼資料,metadata 不一定會填入每個傳送至 Address Validation API 的地址。

欄位
business

bool

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

po_box

bool

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

residential

bool

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

ComponentName

元件名稱包裝函式。

欄位
text

string

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

language_code

string

BCP-47 語言代碼。如果元件名稱未與語言 (例如門牌號碼) 建立關聯,就不會顯示。

Geocode

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

欄位
location

LatLng

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

比起地址、經緯度座標或 Plus Code,最好使用地點 ID。在路線規劃或計算行車路線時使用座標,一律會導致點被對齊到最接近這些座標的道路。這條道路未必能快速或安全導向目的地,而且可能不在房源存取點附近。此外,如果位置是以反向地理編碼的方式進行地理編碼,系統無法保證傳回的地址會與原始地址相符。

plus_code

PlusCode

location 對應的 Plus Code。

bounds

Viewport

經過地理編碼的地點邊界。

feature_size_meters

float

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

place_id

string

這個輸入地理編碼的目標地點的 PlaceID。

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

place_types[]

string

輸入的地理編碼目標地點類型。例如:['locality', 'political']。如需這些類型的完整清單,請參閱本文

LanguageOptions

預覽:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《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」),包含全球代碼的後置字串,並將前置字元換成參照實體的格式化名稱。

ProvideValidationFeedbackRequest

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

欄位
conclusion

ValidationConclusion

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

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

response_id

string

必要欄位。此意見回饋的回覆 ID。在一系列地址驗證嘗試中,這應該是一系列地址驗證中第一個回應的 [response_id][google.maps.addressvalidation.v1. VerifyAddressRequest.response_id]。

ValidationConclusion

處理地址驗證要求序列的最終可能結果。

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

ProvideValidationFeedbackResponse

這個類型沒有任何欄位。

驗證意見回饋的回應。

如果已成功傳送意見回饋,則回應不會有任何內容。

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。

UspsData

地址的 USPS 資料。uspsData 不一定會填入所有傳送至 Address Validation API 的美國或公關地址。如果您使用 uspsData 做為回應的主要部分,建議您在回應中整合備用地址欄位。

欄位
standardized_address

UspsAddress

USPS 標準地址。

delivery_point_code

string

2 位數送貨點代碼

delivery_point_check_digit

string

寄送點檢查碼。這組號碼會加到 delivery_point_barcode 末端,供機械掃描郵件使用。將 delivery_point_barcode、delivery_point_check_digits、郵遞區號和 ZIP+4 的所有數字相加後,就能產生可被 10 除盡的數字。

dpv_confirmation

string

DPV 確認的可能值。傳回單一字元,或不會傳回任何值。

  • N:主要和任何次要電話號碼資訊未能透過 DPV 確認。
  • D:僅針對主要號碼確認地址的 DPV,但缺少次要電話號碼資訊。
  • S:僅針對主要號碼確認地址的 DPV,但有次要號碼資訊,但尚未確認。
  • Y:確認主要號碼和所有次要號碼的地址已通過 DPV。
  • 空白:如果回覆不含 dpv_confirmation 值,則代表沒有為 DPV 確認提交地址。
dpv_footnote

string

提交點驗證中的註腳。同一個字串中可能會串接多個註腳。

  • AA:輸入的地址與 ZIP+4 檔案相符
  • A1:輸入的地址與 ZIP+4 檔案不相符
  • BB:與 DPV (所有元件) 相符
  • CC:次要號碼不相符且不需要
  • C1:次要號碼不相符,但為必填
  • N1:高聳地址缺少次要號碼
  • M1:缺少主要電話號碼
  • M3:主要電話號碼無效
  • P1:輸入地址 PO、RR 或說明中心方塊號碼
  • P3:輸入的地址 PO、RR 或 HC Box 號碼無效
  • F1:輸入的地址與軍事地址相符
  • G1:輸入的地址與一般寄送地址相符
  • U1:輸入的地址與不重複的郵遞區號相符
  • PB:輸入的地址與 PBSA 記錄相符
  • RR:DPV 確認的地址 (包含 PMB 資訊)
  • R1:DPV 確認的地址不含 PMB 資訊
  • R7:電信業者路徑 R777 或 R779 記錄
  • IA:已確認地址資訊
  • TA:透過捨棄結尾的 Alpha 來比對主要號碼
dpv_cmra

string

表示地址是否為 CMRA (商業郵件接收代理商),也就是向客戶接收郵件的私人公司。會傳回單一字元。

  • Y:地址為 CMRA
  • N:這個地址不是 CMRA
dpv_vacant

string

這裡沒空嗎?會傳回單一字元。

  • Y:地址是空的
  • N:地址未合法
dpv_no_stat

string

這裡是否沒有統計資料,或者是有效的地址?沒有統計資料地址是指持續存在的地址,或 USPS 不提供的地址。會傳回單一字元。

  • Y:地址無效
  • N:地址有效
dpv_no_stat_reason_code

int32

表示 NoStat 類型。傳回原因代碼,例如 int。

  • 1:IDA (內部投遞地址) - 不直接從 USPS 接收郵件,但會送至該服務的寄件地址。
  • 2:CDS - 尚未遞送的地址。舉例來說,一個新的子產品群組,在確定數字和主數值時,但尚未針對可住人數建立結構。
  • 3:衝突 - 地址並非實際透過 DPV 確認的地址。
  • 4:CMZ (大專院校、軍事及其他類型) - 將 USPS 納入資料的 ZIP + 4 筆記錄。
  • 5:一般 - 表示未收到外送地址,系統不會將地址視為可能的外送地址。
  • 6:次要必要項目 - 這個地址需要次要資訊。
dpv_drop

string

標記表示郵件會寄送至網站的單一代收訊中。會傳回單一字元。

  • Y:郵件會寄送至網站的單一接待處。
  • N:郵件並非遞送至網站的單一接待員。
dpv_throwback

string

表示郵件未寄到街道地址。會傳回單一字元。

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

string

此標記表示系統不會在一週內每天傳送郵件。會傳回單一字元。

  • Y:系統不會在一週內每天傳送郵件。
  • N:不會顯示任何跡象,代表系統不會在一週每天傳送郵件。
dpv_non_delivery_days_values

int32

用於識別未送達日期的整數。這個時段可以使用位元旗標進行內部測試:0x40 - 星期日是非投遞日 (0x20 – 週一) 非投遞日 (0x10) 和週二 (0x08) 未送達的第 0x08 到 0x04 日到 0x04 到週四未送達的第 0x02 日到星期四未送達

dpv_no_secure_location

string

旗幟表示門可存取,但因為安全考量,包裹不會留下。會傳回單一字元。

  • Y:基於安全考量,包裹不會留下。
  • N:沒有跡象,即使有安全性疑慮,套件也不會留下。
dpv_pbsa

string

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

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

string

旗標 用於指示 USPS 無法敲到大門來傳送郵件的地址。會傳回單一字元。

  • Y:這個門不開放進入。
  • N:沒有跡象顯示門禁上。
dpv_enhanced_delivery_code

string

表示有多個 DPV 傳回代碼適用於該地址。會傳回單一字元。

  • Y:確認主要號碼和所有次要號碼的地址已通過 DPV。
  • N:主要和任何次要電話號碼資訊未能透過 DPV 確認。
  • S:經確認為主要號碼的 DPV,且次要號碼資訊存在但未確認,或捨棄主要號碼的單一追蹤 Alpha 版,以便比對 DPV,並提供次要資訊。
  • D:僅針對主要號碼確認地址的 DPV,但缺少次要電話號碼資訊。
  • R:已確認地址,但已指派給人類路徑 R777 和 R779,但不提供 USPS 遞送。
carrier_route

string

貨運公司的路由代碼。由一個字母前置字元和三位數路徑指定器組成的四個字元代碼。

前置字串:

  • 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:這是指與「Rural Route」或「Highway CommitCT」比對結果,兩者都有相關聯的箱號範圍。
  • S:STREET RECORD:對包含有效主要號碼範圍的街道記錄進行比對。
default_address

bool

這個指標表示系統找到預設地址,但存在更明確的位址。

error_message

string

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

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

cass_processed

bool

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

ValidateAddressRequest

驗證地址的要求。

欄位
address

PostalAddress

必要欄位。要驗證的地址。如要提交未設定格式的地址,請透過 address_lines 提交。

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

如要瞭解支援的區域,請按這裡

輸入位址中的 language_code 值僅限日後使用,今天會遭到忽略。系統會根據指定地址的偏好語言填入已驗證的地址結果,由系統識別。

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

previous_response_id

string

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

enable_usps_cass

bool

啟用 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,第一行包含門牌號碼和名稱,第二行包含城市、州/省和郵遞區號。

language_options

LanguageOptions

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

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

session_token

string

選用設定。用來識別結算用 Autocomplete 工作階段的字串。必須是網址和檔案名稱安全 Base64 字串,且長度不得超過 36 個 ASCII 字元。否則會傳回 INVALID_src 錯誤。

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

注意:地址驗證只能用於採用 Autocomplete (New) API 的工作階段,無法使用 Autocomplete API。詳情請參閱 https://developers.google.com/maps/documentation/places/web-service/session-pricing

ValidateAddressResponse

對地址驗證要求的回應。

欄位
result

ValidationResult

地址驗證的結果。

response_id

string

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

ValidationResult

驗證地址的結果。

欄位
verdict

Verdict

整體判定結果標記

address

Address

與地址本身相關的資訊,與地理編碼不同。

geocode

Geocode

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

metadata

AddressMetadata

與交付項目相關的其他資訊。metadata 不一定會填入每個傳送至 Address Validation API 的地址。

usps_data

UspsData

USPS 提供的額外交付項目標記。僅在區域 USPR 提供。

english_latin_address

Address

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

地址已翻譯成英文,

翻譯的地址無法用做 API 輸入內容。這項服務會提供這些內容,讓使用者可以使用自己的母語確認或拒絕驗證原先提供的地址。

如果地址中有部分沒有英文翻譯,服務會以使用拉丁字母的替代語言傳回該部分。請參閱這篇文章,瞭解系統選擇替代語言的方式。如果地址的一部分沒有任何使用拉丁字母語言的翻譯或音譯,服務會傳回地址相關的當地語言翻譯或音譯。

使用 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

輸入位址的精細程度。這是因為剖析輸入地址後,系統並不會提供任何驗證信號。如要查看驗證信號,請參閱下方的 validation_granularity

舉例來說,如果輸入地址包含特定的公寓號碼,這裡的 input_granularity 就會是 SUB_PREMISE。如果我們無法比對資料庫中的公寓號碼,或是公寓號碼無效,validation_granularity 應該是 PREMISE 以下。

validation_granularity

Granularity

API 可完整validate位址的精細程度。舉例來說,PREMISEvalidation_granularity 表示能驗證 PREMISE 或更粗略的所有地址元件。

如要查看個別地址元件的驗證結果,請前往 google.maps.addressvalidation.v1.Address.address_components

geocode_granularity

Granularity

geocode 精細程度的相關資訊。我們可以理解此地理編碼位置的粗略或精細程度有何語意含意。

這可能與上述的 validation_granularity 不同。例如,資料庫可能記錄了公寓號碼的存在,但無法提供大型公寓大廈的精確地點位置。在這種情況下,validation_granularitySUB_PREMISE,但 geocode_granularity 會是 PREMISE

address_complete

bool

如果沒有未解析的權杖、沒有非預期或缺少的地址元件,則系統會將位址視為已完成。如未設定,表示值為 false。詳情請參閱 missing_component_typesunresolved_tokensunexpected 欄位。

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

精細程度

地址或地理編碼所能具有的各種精細程度。用來表示「地址」的精細程度,用來表示地址識別郵件目的地的精細程度。例如,「123 Main Street, Redwood City, CA, 94061」這類地址可識別 PREMISE,而「紅木城, CA, 94061」這類的地址則可識別 LOCALITY。不過,如果我們找不到紅木城中「123 Main Street」的地理編碼,則傳回的地理編碼可能會是 LOCALITY 的精細程度,即使地址更精細。

列舉
GRANULARITY_UNSPECIFIED 預設值。這個值未使用。
SUB_PREMISE 低於建築物等級的結果,例如公寓。
PREMISE 建築物層級結果。
PREMISE_PROXIMITY 模擬地址建築物層級位置的地理編碼。
BLOCK 地址或地理編碼表示區塊。僅適用於具有區塊層級定址的區域,例如日本。
ROUTE 地理編碼或地址是路線的精細程度,例如街道、道路或高速公路。
OTHER 所有其他精細程度 (因為無法交付,所以會歸為一組)。