Package google.maps.addressvalidation.v1

索引

AddressValidation

用於驗證地址的服務。

ProvideValidationFeedback

rpc ProvideValidationFeedback(ProvideValidationFeedbackRequest) returns (ProvideValidationFeedbackResponse)

關於驗證嘗試序列結果的意見回饋。這是針對相同地址的一系列驗證呼叫後,最後一次呼叫,且應在交易結束後呼叫。對於需要完整驗證地址的 ValidateAddress 要求序列,此值應只傳送一次。

ValidateAddress

rpc ValidateAddress(ValidateAddressRequest) returns (ValidateAddressResponse)

驗證地址。

地址

後處理地址的詳細資料。後置處理包括修正地址中拼錯的部分、取代不正確的部分,以及推斷遺漏的部分。

欄位
formatted_address

string

經後處理的地址,格式為單行地址,並遵循地址所在區域的地址格式規則。

注意:此地址的格式可能與 postal_address 欄位中的地址格式不符。舉例來說,postal_address 一律會以 2 個字母 region_code 表示國家/地區,例如「US」或「NZ」。相較之下,這個欄位會使用較長的國家/地區名稱,例如「美國」或「紐西蘭」。

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

輸入內容中無法解析的任何符記。這可能是系統無法辨識為有效地址的輸入內容。舉例來說,如果輸入的內容是「Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US」,未解析的符記可能會是 ["Parcel", "0000123123", "&", "0000456456"]

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

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

建議您使用地點 ID,而非地址、經緯度座標或 Plus Code。在規劃路線或計算行車路線時使用座標,系統一律會將點對齊最接近該座標的道路。這條路可能無法快速或安全地通往目的地,也可能不在房源附近。此外,當位置經過反向地理編碼後,傳回的地址不一定會與原始地址相符。

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) 是一種位置參照,有兩種格式:全球代碼定義 14 公尺 x 14 公尺 (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 資料。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_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 或 HC 信箱號碼
  • P3:輸入的地址 PO、RR 或 HC 信箱號碼無效
  • 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 (大學、軍事和其他類型) - 美國郵政署已納入資料的郵遞區編號 + 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 – 週三為非送達日 0x04 – 週四為非送達日 0x02 – 週五為非送達日 0x01 – 週六為非送達日

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 比對,次要號碼資訊雖然存在但未經確認,或是主要號碼的單一尾碼遭到刪除,導致 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 (Private Mail Box) 號碼

address_record_type

string

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

  • F:FIRM。這是與「確實記錄」的比對結果,這是地址可用的最精確比對結果。
  • G:一般交付。這項資訊與一般寄送記錄相符。
  • H:建築物/公寓。這項資料與建築物或公寓記錄相符。
  • P:郵政信箱。這是與郵政信箱的配對結果。
  • R:RURAL ROUTE 或 HIGHWAY CONTRACT:這是 Rural Route 或 Highway Contract 記錄的配對結果,兩者都可能有相關的 Box Number 範圍。
  • 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 的要求,addressgoogle.type.PostalAddress.region_code 必須提供為「PR」,或是 addressgoogle.type.PostalAddress.administrative_area 必須提供為「Puerto Rico」(不區分大小寫) 或「PR」。

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

language_options

LanguageOptions

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

讓 Address Validation API 在回應中加入其他資訊。

session_token

string

選用設定。用於計費的 Autocomplete 工作階段識別字串。必須是安全的 base64 字串,且長度不得超過 36 個 ASCII 字元。否則會傳回 INVALID_ARGUMENT 錯誤。

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

注意:Address Validation 只能用於使用 Autocomplete (新版) 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

由美國郵政署提供的其他可送達性標記。僅提供 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 可用來完整驗證地址的精細程度。舉例來說,如果 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

如果沒有未解析的符記,且地址中沒有任何意外或遺漏的組件,則系統會將地址視為完整。如果未設定,表示值為 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。不過,如果我們找不到位於 Redwood City 的「123 Main Street」地理編碼,則即使地址更精確,系統仍可能會傳回 LOCALITY 精確度的地理編碼。

列舉
GRANULARITY_UNSPECIFIED 預設值。這個值未使用。
SUB_PREMISE 建築物以下的結果,例如公寓。
PREMISE 大樓層級結果。
PREMISE_PROXIMITY 大致符合地址建築物層級位置的地理編碼。
BLOCK 地址或地理編碼代表街區。僅用於有區塊層級位址的地區,例如日本。
ROUTE 地理編碼或地址是路線的精細程度,例如街道、道路或高速公路。
OTHER 所有其他精細度 (由於無法傳送,因此會歸入同一類別)。