Package google.maps.addressvalidation.v1

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

索引

驗證地址

用來驗證地址的服務。

提供驗證意見回饋

rpc ProvideValidationFeedback(ProvideValidationFeedbackRequest) returns (ProvideValidationFeedbackResponse)

針對嘗試驗證順序的結果提供意見回饋。這應該是針對同一個位址的一系列驗證呼叫之後所發出的最後一個呼叫，且會在交易完成後呼叫。這個方法只應用於完整驗證地址所需的 ValidateAddress 要求順序。
驗證地址

rpc ValidateAddress(ValidateAddressRequest) returns (ValidateAddressResponse)

驗證地址。

Address

從輸入內容剖析的地址詳細資料。

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

表示元件名稱的拼寫方式有小幅校正，例如切換兩個錯誤的排序字元。這代表外觀變化。
replaced

bool

表示元件名稱已完全更換，例如將郵遞區號取代為正確的地址。這項變更並非外觀異動，輸入元件已變更為其他元件。
unexpected

bool

指出某個地區的地址無法預期出現在地址中的地址元件。目前這是保留的，因為這是輸入內容的一部分。

確認等級

確認等級的不同可能值。

列舉
CONFIRMATION_LEVEL_UNSPECIFIED 預設值。未使用這個值。
CONFIRMED 我們能夠驗證此元件是否存在，並且瞭解在地址的其他部分。
UNCONFIRMED_BUT_PLAUSIBLE 系統無法確認這個元件，但這個元件可能存在。例如，街道上的已知有效號碼範圍中，門牌號碼並不知道；
UNCONFIRMED_AND_SUSPICIOUS 這個元件尚未經過確認，可能有誤。例如，不符合其他地址的鄰近地區。

位址中繼資料

位址的中繼資料。metadata 無法保證系統每次傳送到 Address Authentication 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 相對應的 Plus Code。
bounds

Viewport

地理編碼地點的邊界。
feature_size_meters

float

地理編碼地點的大小 (以公尺為單位)。這是另一個進行地理編碼位置粗糙度的測量結果，但會以實體大小而非語意含義。
place_id

string

此輸入內容定位點的 PlaceID。

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

string

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

PlusCode

Plus Code (http://plus.codes) 是位置參照和兩種格式：全域碼，定義 14mx14m (角度 1/8000) 或更小的矩形，以及複合程式碼，以前置字元位置取代前置字元。

欄位
global_code

string

Place 的全局（完整）代碼，例如“9FWM33GV+HQ”，代表 1/8000 x 1/8000 度面積（~14 x 14 米）。
compound_code

string

地點的複合程式碼，例如「33GV+HQ、Ramberg、挪威」，內含全域碼的後置字串，並以參照實體名稱的格式取代前置字元。

提供驗證意見回饋的請求

要求提供驗證意見回饋。

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

UspsData 資料

地址的 USPS 資料。uspsData 無法保證系統可對所有傳送至 Address Authentication API 的美國或 PR 地址填入資料。如果您使用 uspsData 做為回應的主要部分，建議將回應中的地址欄位整合在回應中。

欄位
standardized_address

UspsAddress

USPS 標準化地址。
delivery_point_code

string

2 位數交貨地點代碼
delivery_point_check_digit

string

運送點檢查碼。這組編號會加至掃描號碼的 delivery_point_barcode 結尾。5.
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 或 HC Box 號碼無效
  • F1：輸入地址與軍用地址相符
  • G1：輸入地址與一般配送地址相符
  • U1：輸入地址與一個專屬郵遞區號相符
  • PB：輸入地址與 PBSA 記錄相符
  • RR：DPV 確認地址，搭配 PMB 資訊
  • R1：已確定沒有 PMB 資訊的 DPV 確認地址
  • 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

航空公司路線代碼。由四碼字首和三位數路線指示符組成的四字元代碼。

前置字元：

  • 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 記錄，這是比對地址的最佳比對等級。
  • G：一般配送。這與一般放送記錄相符。
  • H：建築物/公寓這與建築物或公寓記錄相符。
  • P：發布通知方塊。此為「郵局箱」的結果。
  • R：路程範圍或公路高度：這與鄉村路線或公路合約紀錄相符，兩者皆有相關聯的 Box 號碼範圍。
  • 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，其中第一行包含街道號碼和名稱，第二行包含城市、州和郵遞區號。

驗證地址回應

回應地址驗證要求。

欄位
result

ValidationResult

地址驗證的結果。
response_id

string

用來識別此回應的 UUID。如果需要重新驗證地址，這個 UUID 必須附在新的要求中。

ValidationResult

驗證地址的結果。

欄位
verdict

Verdict

整體判定結果標記
address

Address

地址本身，而非地理編碼。
geocode

Geocode

地址所對應的地點和地點相關資訊。
metadata

AddressMetadata

其他交付相關資訊。metadata 無法保證系統每次傳送到 Address Authentication API 的地址時，都能找到完整的地址。
usps_data

UspsData

USPS 提供的額外交付旗標。僅於 US 和 PR 地區提供。

評斷

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

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

精細程度

地址或地理編碼可設定的各種精細程度。這些值是用來表示「地址」的精細程度時，用來指出地址識別郵件的精細程度。舉例來說，如果地址為「123 Main Street, Redwood City, CA, 94061」，地址就會變成 PREMISE，而「Redwood City, CA, 94061」則可用來辨識LOCALITY。然而，如果我們無法在紅木城找不到「中正路 123 號」的地理編碼，即使地址較為精細，傳回的地理編碼可能仍是 LOCALITY 的精細程度。

列舉
GRANULARITY_UNSPECIFIED 預設值。未使用這個值。
SUB_PREMISE 低於建築物等級的結果，例如公寓。
PREMISE 建築物層級結果。
PREMISE_PROXIMITY 這個地理編碼值應該非常接近地址的建築物層級位置。僅適用於地理編碼，不適用於地址。
BLOCK 地址或地理編碼表示區塊遭到封鎖。僅適用於適用區塊層級位址的區域，例如日本。
ROUTE 地理編碼或地址十分精細，例如街道、道路或高速公路。
OTHER 所有其他因為分類無法交付而已分離的精細程度。