索引
AddressValidation
(介面)Address
(訊息)AddressComponent
(訊息)AddressComponent.ConfirmationLevel
(列舉)AddressMetadata
(訊息)ComponentName
(訊息)Geocode
(訊息)LanguageOptions
(訊息)PlusCode
(訊息)ProvideValidationFeedbackRequest
(訊息)ProvideValidationFeedbackRequest.ValidationConclusion
(列舉)ProvideValidationFeedbackResponse
(訊息)UspsAddress
(訊息)UspsData
(訊息)ValidateAddressRequest
(訊息)ValidateAddressResponse
(訊息)ValidationResult
(訊息)Verdict
(訊息)Verdict.Granularity
(列舉)
AddressValidation
用於驗證地址的服務。
ProvideValidationFeedback |
---|
關於驗證嘗試序列結果的意見回饋。這是針對相同地址的一系列驗證呼叫後,最後一次呼叫,且應在交易結束後呼叫。對於需要完整驗證地址的 |
ValidateAddress |
---|
驗證地址。 |
地址
後處理地址的詳細資料。後置處理包括修正地址中拼錯的部分、取代不正確的部分,以及推斷遺漏的部分。
欄位 | |
---|---|
formatted_ |
經後處理的地址,格式為單行地址,並遵循地址所在區域的地址格式規則。 注意:此地址的格式可能與 |
postal_ |
經後處理的地址,以郵寄地址表示。 |
address_ |
未排序的清單。經過修正的地址格式和修正後的地址,以及驗證資訊。這可提供個別元件的驗證狀態資訊。 地址元件並未依特定順序排列。請勿對清單中地址元件的排序做出任何假設。 |
missing_ |
在正確格式的郵寄地址中,應有的元件類型,但在輸入內容中找不到,也無法推斷。這類元件不會出現在 |
unconfirmed_ |
|
unresolved_ |
輸入內容中無法解析的任何符記。這可能是系統無法辨識為有效地址的輸入內容。舉例來說,如果輸入的內容是「Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US」,未解析的符記可能會是 |
AddressComponent
代表地址元件,例如街道、城市或州。
欄位 | |
---|---|
component_ |
這個元件的名稱。 |
component_ |
地址元件的類型。請參閱「表 2:地點介面集服務傳回的其他類型」,瞭解可能類型的清單。 |
confirmation_ |
表示我們對元件正確性的信心程度。 |
inferred |
表示該元件並非輸入內容的一部分,但我們已推斷出地址位置,並認為應提供完整地址。 |
spell_ |
表示修正元件名稱中的錯字。API 不一定會標示拼法變化,例如將「centre」改為「center」。此外,不一定能標記常見的錯別字,例如將「Amphitheater Pkwy」改為「Amphitheatre Pkwy」。 |
replaced |
表示元件名稱已替換為完全不同的名稱,例如錯誤的郵遞區號已替換為地址正確的郵遞區號。這不是外觀上的變更,而是輸入元件已變更為其他元件。 |
unexpected |
表示在特定區域的郵遞地址中,不應出現的地址元件。我們只保留該值,因為它是輸入內容的一部分。 |
ConfirmationLevel
確認層級的不同可能值。
列舉 | |
---|---|
CONFIRMATION_LEVEL_UNSPECIFIED |
預設值。這個值未使用。 |
CONFIRMED |
我們已確認這個元件確實存在,且在地址的其他部分中也合理。 |
UNCONFIRMED_BUT_PLAUSIBLE |
我們無法確認這個元件,但它可能存在。例如路上已知有效號碼範圍內的門牌號碼,但系統無法識別特定門牌號碼。 |
UNCONFIRMED_AND_SUSPICIOUS |
這個元件未經確認,可能有誤。例如,不符合地址其餘部分的鄰里。 |
AddressMetadata
位址的中繼資料,metadata
不保證會為傳送至 Address Validation API 的每個地址完整填入資料。
欄位 | |
---|---|
business |
表示這是商家地址。如果未設定,則表示值不明。 |
po_ |
表示郵政信箱的地址。如果未設定,則表示值不明。 |
residential |
表示這是住家地址。如果未設定,則表示值不明。 |
ComponentName
元件名稱的包裝函式。
欄位 | |
---|---|
text |
名稱文字。例如街道名稱「5th Avenue」或門牌號碼「1253」。 |
language_ |
BCP-47 語言代碼。如果元件名稱未與語言 (例如門牌號碼) 建立關聯,就不會顯示。 |
Geocode
包含輸入內容經過地理編碼後的地點資訊。
欄位 | |
---|---|
location |
輸入內容的地理編碼位置。 建議您使用地點 ID,而非地址、經緯度座標或 Plus Code。在規劃路線或計算行車路線時使用座標,系統一律會將點對齊最接近該座標的道路。這條路可能無法快速或安全地通往目的地,也可能不在房源附近。此外,當位置經過反向地理編碼後,傳回的地址不一定會與原始地址相符。 |
plus_ |
與 |
bounds |
已編碼地點的邊界。 |
feature_ |
經過地理編碼的地點大小,以公尺為單位。這是另一種評估地理編碼位置粗略性的測量方法,但實際大小而非語意上的含義。 |
place_ |
這個輸入內容地理編碼的地點 PlaceID。 如要進一步瞭解地點 ID,請參閱這篇文章。 |
place_ |
輸入內容經地理編碼後的地點類型。例如: |
LanguageOptions
預先發布版:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明。
讓 Address Validation API 在回應中加入其他資訊。
欄位 | |
---|---|
return_ |
預覽:傳回英文的 |
PlusCode
Plus Code (http://plus.codes) 是一種位置參照,有兩種格式:全球代碼定義 14 公尺 x 14 公尺 (1/8000 度) 或更小的矩形,複合代碼則會將前置字元替換為參照位置。
欄位 | |
---|---|
global_ |
地點的全球 (完整) 代碼,例如「9FWM33GV+HQ」,代表 1/8000 度 x 1/8000 度 (約 14 公尺 x 14 公尺) 的面積。 |
compound_ |
地點的複合代碼 (例如「33GV+HQ, Ramberg, Norway」),包含全球代碼的後置字串,並將前置字元換成參照實體的格式化名稱。 |
ProvideValidationFeedbackRequest
要求傳送驗證意見回饋。
欄位 | |
---|---|
conclusion |
必要欄位。驗證嘗試序列的結果。 如果將這個欄位設為 |
response_ |
必要欄位。這項意見回饋所屬的回應 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_ |
第一行地址。 |
firm |
公司名稱。 |
second_ |
第二個地址行。 |
urbanization |
波多黎各都市化名稱。 |
city_ |
城市 + 州 + 郵遞區號。 |
city |
城市名稱。 |
state |
由 2 個英文字母組成的州代碼。 |
zip_ |
郵遞區號,例如 10009。 |
zip_ |
4 位數郵遞區號擴充碼,例如 5023。 |
UspsData
地址的 USPS 資料。uspsData
不一定會填入所有傳送至 Address Validation API 的美國或公關地址。如果您將 uspsData 用於回應的主要部分,建議您在回應中整合備用地址欄位。
欄位 | |
---|---|
standardized_ |
USPS 標準格式地址。 |
delivery_ |
2 位數交貨地點代碼 |
delivery_ |
運送地點檢查碼。這組號碼會加到 delivery_point_barcode 末端,供機械掃描郵件使用。將 delivery_point_barcode、delivery_point_check_digit、郵遞區號和 ZIP+4 的所有數字加總後,所得的數字應可被 10 整除。 |
dpv_ |
DPV 確認的可能值。傳回單一字元或不傳回任何值。
|
dpv_ |
交付點驗證的註腳。多個腳註可連結在一起,並串連在同一個字串中。
|
dpv_ |
指出地址是否為 CMRA (商業郵件收件代理機構),也就是為客戶收取郵件的私人企業。會傳回單一字元。
|
dpv_ |
這個地點是否有空位?會傳回單一字元。
|
dpv_ |
這是無統計資料地址還是有效地址?無統計資料的地址是指未持續有人居住的地址,或 USPS 未提供服務的地址。傳回單一字元。
|
dpv_ |
表示 NoStat 類型。傳回原因代碼,例如 int。
|
dpv_ |
標記表示郵件已送至網站上的單一收件匣。傳回單一字元。
|
dpv_ |
表示郵件未送達街道地址。會傳回單一字元。
|
dpv_ |
此標記表示系統不會在一週內每天傳送郵件。傳回單一字元。
|
dpv_ |
整數,用於識別未放送日。您可以使用位元旗標查詢:0x40 – 週日為非送達日 0x20 – 週一為非送達日 0x10 – 週二為非送達日 0x08 – 週三為非送達日 0x04 – 週四為非送達日 0x02 – 週五為非送達日 0x01 – 週六為非送達日 |
dpv_ |
標記表示門可供存取,但基於安全考量,包裹不會留在門口。傳回單一字元。
|
dpv_ |
表示地址與 PBSA 記錄相符。會傳回單一字元。
|
dpv_ |
旗標 用於指示 USPS 無法敲到大門來傳送郵件的地址。傳回單一字元。
|
dpv_ |
表示有多個 DPV 傳回代碼適用於該地址。會傳回單一字元。
|
carrier_ |
運送公司路線代碼。四個字元的代碼,包含一個英文字母前置字串和三位數路線標記。 前置字串:
|
carrier_ |
貨運公司轉送率排序指標。 |
ews_ |
雖然運送地址可比對,但 EWS 檔案指出,不久後就會提供完全比對的結果。 |
post_ |
主要郵局所在城市。 |
post_ |
主要郵局狀態。 |
abbreviated_ |
城市縮寫。 |
fips_ |
FIPS 縣/郡代碼。 |
county |
郡/縣名稱。 |
elot_ |
進階交通線 (eLOT) 號碼。 |
elot_ |
eLOT 遞增/遞減旗標 (A/D)。 |
lacs_ |
LACSLink 傳回代碼。 |
lacs_ |
LACSLink 指示燈。 |
po_ |
郵政信箱郵遞區號。 |
suitelink_ |
街道或高樓記錄與套房資訊比對後產生的附註。如果找到相符的商家名稱,系統會傳回次要號碼。
|
pmb_ |
PMB (私人信箱) 單位指定員。 |
pmb_ |
PMB (Private Mail Box) 號碼 |
address_ |
與輸入地址相符的地址記錄類型。
|
default_ |
表示已找到預設地址,但有更具體的地址。 |
error_ |
USPS 資料擷取錯誤訊息。當 USPS 偵測到人為建立的地址,系統就會暫停處理。 發生這項錯誤時,系統可能不會填入 USPS 資料欄位。 |
cass_ |
表示要求已由 CASS 處理的指標。 |
ValidateAddressRequest
要求驗證地址。
欄位 | |
---|---|
address |
必要欄位。要驗證的地址。未經格式化的地址應透過 此輸入內容中欄位的總長度不得超過 280 個字元。 如要查看支援的區域,請按這裡。 輸入位址中的 Address Validation API 會忽略 |
previous_ |
在第一次地址驗證要求中,這個欄位必須留空。如果需要更多要求才能完整驗證單一地址 (例如,如果使用者在初始驗證後所做的變更需要重新驗證),則每個後續要求都必須在這個欄位中填入驗證序列中第一個回應的 |
enable_ |
啟用 USPS CASS 相容模式。這項變更只會影響 建議您使用元件化 |
language_ |
選用設定。預先發布版:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明。 讓 Address Validation API 在回應中加入其他資訊。 |
session_ |
選用設定。用於計費的 Autocomplete 工作階段識別字串。必須是安全的 base64 字串,且長度不得超過 36 個 ASCII 字元。否則會傳回 INVALID_ARGUMENT 錯誤。 使用者執行自動完成查詢時,工作階段就會開始,並在使用者選取地點並呼叫 PlaceDetails 或 AddressValidation 時結束。每個工作階段都可以有多項 Autocomplete 查詢,後面接著一筆 Place Details 或 Address Validation。在單一工作階段中,每項要求使用的憑證都必須屬於同一個 Google Cloud 控制台專案。工作階段結束後,符記就會失效;應用程式必須為每個工作階段產生新的符記。如果省略 注意:Address Validation 只能用於使用 Autocomplete (新版) API 的工作階段,而非 Autocomplete API。詳情請參閱 https://developers.google.com/maps/documentation/places/web-service/session-pricing。 |
ValidateAddressResponse
回應地址驗證要求。
欄位 | |
---|---|
result |
地址驗證結果。 |
response_ |
用於識別此回應的 UUID。如需重新驗證地址,新的要求「必須」搭配這個 UUID。 |
ValidationResult
驗證地址的結果。
欄位 | |
---|---|
verdict |
整體判定結果標記 |
address |
地址本身的資訊,而非地理編碼。 |
geocode |
地址地理編碼的所在位置和地點資訊。 |
metadata |
與交付項目相關的其他資訊。 |
usps_ |
由美國郵政署提供的其他可送達性標記。僅提供 |
english_ |
預先發布版:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明。 已翻譯成英文的地址。 翻譯的地址無法用於 API 輸入。這項服務可讓使用者透過自己的母語確認或拒絕原先所提供地址的驗證作業。 如果部分地址沒有英文翻譯,服務會以使用拉丁字母的其他語言傳回該部分。如要瞭解系統如何選取替代語言,請參閱這篇文章。如果地址的一部分沒有任何使用拉丁字母語言的翻譯或音譯,服務會傳回地址相關的當地語言翻譯或音譯。 使用 注意: |
判定結果
地址驗證結果和地理編碼的概略總覽。
欄位 | |
---|---|
input_ |
輸入地址的精細程度。這是剖析輸入地址的結果,不會提供任何驗證信號。如需驗證信號,請參閱下方的 舉例來說,如果輸入地址包含特定的公寓號碼,這裡的 |
validation_ |
API 可用來完整驗證地址的精細程度。舉例來說,如果 您可以在 |
geocode_ |
這可能與上述 |
address_ |
如果沒有未解析的符記,且地址中沒有任何意外或遺漏的組件,則系統會將地址視為完整。如果未設定,表示值為 |
has_ |
至少有一個地址元件無法分類或驗證,詳情請參閱 |
has_ |
系統推斷 (新增) 了至少一個未在輸入內容中的地址元件,詳情請參閱 |
has_ |
至少有一個地址元件遭到取代,詳情請參閱 |
精細程度
地址或地理編碼可具有的各種精細程度。當用於表示地址的精細程度時,這些值會指出地址如何識別郵寄目的地的精細程度。例如,「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 |
所有其他精細度 (由於無法傳送,因此會歸入同一類別)。 |