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

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

欄位
business

bool

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

po_box

bool

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

residential

bool

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

ComponentName

元件名稱的包裝函式。

欄位
text

string

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

language_code

string

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

Geocode

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

欄位
location

LatLng

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

比起使用地址、經緯度座標或加號,更建議使用地點 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.ValidateAddressRequest.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 資料。我們不保證會為每個傳送至 Address Validation API 的美國或 PR 位址完整填入 uspsData。如果您使用 uspsData 做為回應的主要部分,建議您在回應中整合備用地址欄位。

欄位
standardized_address

UspsAddress

USPS 標準化位址。

delivery_point_code

string

2 位數寄送點代碼

delivery_point_check_digit

string

寄送點檢查碼。這個號碼會加入用於自動掃描郵件,在 Delivery_point_barcode 末端所加上的號碼。將 send_point_barcode、delivery_point_check_digit、郵遞區號和 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:缺少輸入地址訂購單、RR 或說明中心方塊號碼
  • P3:輸入地址訂購單、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 (大專院校、軍事和其他類型) - ZIP + 4 記錄 USPS 已納入資料中。
  • 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 – 星期一是 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

貨運公司路線代碼。由 1 個字母前置字元和 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。這會與「Firm Record」相符,這是針對某地址提供最精細的比對等級。
  • G:一般交付。這項資訊與一般配送記錄相符。
  • H:建立 / 交集。這個值與建築物或公寓記錄相符。
  • P:張貼方塊。這是與郵政信箱完全相符的項目。
  • R: RURAL ROUTE 或 HighWAY PASCT:與鄉村路線或高速公路合約記錄相符,兩者都可能有相關聯的裝箱編號範圍。
  • 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_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

ValidateAddressResponse

地址驗證要求的回應。

欄位
result

ValidationResult

地址驗證的結果。

response_id

string

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

ValidationResult

驗證地址的結果。

欄位
verdict

Verdict

整體判定結果標記

address

Address

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

geocode

Geocode

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

metadata

AddressMetadata

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

usps_data

UspsData

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

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

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

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

validation_granularity

Granularity

API 可完整「驗證」validate地址的目標精細程度。舉例來說,如果 validation_granularityPREMISE,代表可以驗證 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_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,而「Redwood City, CA, 94061」則代表 LOCALITY。不過,如果我們無法在紅木市找到「123 Main Street」的地理編碼,則傳回的地理編碼可能會是 LOCALITY 的精細度。

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