- HTTP 要求
- 要求主體
- 回應主體
- PostalAddress
- LanguageOptions
- ValidationResult
- 判定結果
- 精細程度
- 地址
- AddressComponent
- ComponentName
- ConfirmationLevel
- 地理編碼
- LatLng
- PlusCode
- Viewport
- AddressMetadata
- UspsData
- UspsAddress
驗證地址。
HTTP 要求
POST https://addressvalidation.googleapis.com/v1:validateAddress
這個網址使用 gRPC 轉碼語法。
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{ "address": { object ( |
欄位 | |
---|---|
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。 |
回應主體
對地址驗證要求的回應。
如果成功,回應主體會含有以下結構的資料:
JSON 表示法 |
---|
{
"result": {
object ( |
欄位 | |
---|---|
result |
地址驗證結果。 |
response |
用於識別此回應的 UUID。如需重新驗證地址,新的要求「必須」搭配這個 UUID。 |
PostalAddress
表示郵寄地址,如郵政快遞或付款地址。如果是郵寄地址,郵政服務可將貨品寄送到場所、郵政信箱或類似位置。此表示法並不適用於建立地理位置 (街道、鄉鎮或山區) 的模型。
在一般使用情況下,系統會根據處理作業的類型,以使用者輸入或匯入現有資料的方式來建立地址。
地址輸入/編輯的建議:- 使用支援國際化的地址小工具 (例如 https://github.com/google/libaddressinput) - 在使用者使用該欄位的國家/地區外,不應向使用者顯示用於輸入或編輯欄位的 UI 元素。
如要進一步瞭解如何使用這個結構定義,請參閱:https://support.google.com/business/answer/6397478
JSON 表示法 |
---|
{ "revision": integer, "regionCode": string, "languageCode": string, "postalCode": string, "sortingCode": string, "administrativeArea": string, "locality": string, "sublocality": string, "addressLines": [ string ], "recipients": [ string ], "organization": string } |
欄位 | |
---|---|
revision |
|
region |
選用設定。地址所在國家/地區的 CLDR 地區代碼。詳情請參閱 https://cldr.unicode.org/ 和 https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html。例如:瑞士的地區代碼為「CH」。如果未提供區域代碼,系統會根據地址推斷。為獲得最佳效能,建議您加入區碼。不一致或重複的區域可能會導致效能不佳。舉例來說,如果 |
language |
輸入地址中的語言代碼只保留供日後使用,今天會遭到忽略。API 會以地址所在地的適當語言傳回地址。 |
postal |
選用設定。地址的郵遞區號。並非所有國家/地區都使用郵遞區號或要求必須填寫郵遞區號,不過在使用郵遞區號時,可能會對地址其他部分觸發額外的驗證作業 (例如美國對州/郵遞區號的驗證)。 |
sorting |
選用設定。國家/地區專屬的其他分類代碼。大多數國家/地區並不使用這個代碼。在使用分類代碼的國家/地區中,這個值為與「CEDEX」相似的字串,後面選擇性加上一個數字 (例如「CEDEX 7」),或是只有單一數字,並用來表示「區段代碼」(牙買加)、「寄送區域指示碼」(馬拉威) 或「郵局指示碼」(如象牙海岸)。 |
administrative |
選用設定。最高行政區,用於國家/地區的郵遞地址。例如,此值可以是州、省或縣。以西班牙為例來具體說明,此欄位的值為省,而非自治區 (例如「巴塞隆納」省,而不是「加泰隆尼亞」自治區)。許多國家/地區的郵寄地址並沒有使用行政區。例如,就瑞士而言,該欄位應該留空不填。 |
locality |
選用設定。一般是指地址的縣市/鄉鎮部分。例如:美國城市、義大利市鎮、英國郵鎮。如為未明確定義縣市或其縣市不適用此結構的地區,請將 locality 留白,改用 addressLines。 |
sublocality |
選用設定。地址的縣市以下行政區,例如社區、自治市鎮和區等。 |
address |
必要欄位。非結構化的地址行,說明地址的低層級項目。 |
recipients[] |
請勿設定此欄位。Address Validation API 目前並未使用。雖然目前 API 不會拒絕含有此欄位的請求,但系統會捨棄該資訊,不會在回應中傳回。 |
organization |
請勿設定此欄位。Address Validation API 目前並未使用。雖然目前 API 不會拒絕含有此欄位設定的要求,但系統會捨棄該資訊,不會在回應中傳回。 |
LanguageOptions
預先發布版:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明。
啟用 Address Validation API,在回應中加入其他資訊。
JSON 表示法 |
---|
{ "returnEnglishLatinAddress": boolean } |
欄位 | |
---|---|
return |
預覽:以英文傳回 |
ValidationResult
驗證地址的結果。
JSON 表示法 |
---|
{ "verdict": { object ( |
欄位 | |
---|---|
verdict |
整體判定結果標記 |
address |
地址本身的資訊,而非地理編碼。 |
geocode |
地址地理編碼的所在位置和地點資訊。 |
metadata |
其他與可送達性相關的資訊。 |
usps |
USPS 提供的額外交付項目標記。僅提供 |
english |
預覽:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明。 已翻譯成英文的地址。 翻譯的地址無法用於 API 輸入。服務會提供這些選項,方便使用者以母語確認或否認原先提供的地址是否有效。 如果地址中有部分沒有英文翻譯,服務會以使用拉丁字母的替代語言傳回該部分。請參閱這篇文章,瞭解系統選擇替代語言的方式。如果部分地址沒有使用拉丁字母系統的語言翻譯或轉寫,服務會以與地址相關聯的當地語言傳回該部分。 使用 注意: |
判定結果
地址驗證結果和地理編碼的概略總覽。
JSON 表示法 |
---|
{ "inputGranularity": enum ( |
欄位 | |
---|---|
input |
輸入地址的精細程度。這是剖析輸入地址的結果,不會提供任何驗證信號。如需驗證信號,請參閱下方的 舉例來說,如果輸入的地址包含特定公寓號碼,這裡的 |
validation |
API 可完整驗證位址的精細程度。舉例來說, 如要查看個別地址元件的驗證結果,請前往 |
geocode |
這可能與上述的 |
address |
如果沒有未解析的符記,且地址中沒有任何意外或遺漏的組件,則系統會將地址視為完整。如果未設定,表示值為 |
has |
至少有一個地址元件無法分類或驗證,詳情請參閱 |
has |
系統推斷 (新增) 了至少一個未在輸入內容中的地址元件,詳情請參閱 |
has |
至少一個地址元件遭到取代,詳情請參閱 |
精細程度
地址或地理編碼可具有的各種精細程度。用來表示「地址」的精細程度時,這些值可用來表示地址識別郵件目的地的精細程度。舉例來說,「123 Main Street, Redwood City, CA, 94061」這類地址會識別 PREMISE
,而「Redwood City, CA, 94061」這類地址則會識別 LOCALITY
。不過,如果我們找不到位於 Redwood City 的「123 Main Street」地理編碼,則即使地址更精確,系統仍可能會傳回 LOCALITY
精確度的地理編碼。
列舉 | |
---|---|
GRANULARITY_UNSPECIFIED |
預設值。這個值未使用。 |
SUB_PREMISE |
建築物以下的結果,例如公寓。 |
PREMISE |
大樓層級結果。 |
PREMISE_PROXIMITY |
大致符合地址建築物層級位置的地理編碼。 |
BLOCK |
地址或地理編碼代表街區。僅用於有區塊層級位址的地區,例如日本。 |
ROUTE |
地理編碼或地址是精細的路線,例如街道、道路或高速公路。 |
OTHER |
所有其他精細程度 (由於無法交付,所以會歸為一組)。 |
地址
後處理地址的詳細資料。後置處理包括修正地址中拼錯的部分、取代不正確的部分,以及推斷遺漏的部分。
JSON 表示法 |
---|
{ "formattedAddress": string, "postalAddress": { object ( |
欄位 | |
---|---|
formatted |
經後處理的地址,格式為單行地址,並遵循地址所在區域的地址格式規則。 注意:此地址的格式可能與 |
postal |
經後處理的地址,以郵寄地址表示。 |
address |
未排序的清單。經過修正的地址格式和修正後的地址,以及驗證資訊。這可提供個別元件的驗證狀態資訊。 地址元件並未依特定順序排列。請勿對清單中地址元件的排序做出任何假設。 |
missing |
預期會出現在正確格式郵寄地址中,但輸入中卻找不到的元件類型,「而且」系統無法推斷出這些元件類型。這類元件不會出現在 |
unconfirmed |
|
unresolved |
輸入資料中有任何無法解析的權杖。這可能是系統無法辨識為有效地址的輸入內容。舉例來說,如果輸入的內容是「Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US」,未解析的符記可能會是 |
AddressComponent
代表地址元件,例如街道、城市或州/省。
JSON 表示法 |
---|
{ "componentName": { object ( |
欄位 | |
---|---|
component |
此元件的名稱。 |
component |
地址元件的類型。如需可能類型的清單,請參閱「表 2:地點介面集服務傳回的其他類型」。 |
confirmation |
指出元件正確無誤的確定程度。 |
inferred |
表示該元件並非輸入內容的一部分,但我們已推斷出地址位置,並認為應提供完整地址。 |
spell |
表示修正元件名稱中的拼寫錯誤。API 不一定會標示拼法變化,例如將「centre」改為「center」。而且也不一定會標示常見的拼寫錯誤,例如將「Amphitheater Pkwy」改為「Amphitheatre Pkwy」。 |
replaced |
表示元件名稱已替換為完全不同的名稱,例如錯誤的郵遞區號已替換為地址正確的郵遞區號。這不是外觀上的變更,而是輸入元件已變更為其他元件。 |
unexpected |
表示在特定區域的郵遞地址中,不應出現的地址元件。我們只保留該值,因為它是輸入內容的一部分。 |
ComponentName
元件名稱的包裝函式。
JSON 表示法 |
---|
{ "text": string, "languageCode": string } |
欄位 | |
---|---|
text |
名稱文字。例如街道名稱「5th Avenue」或門牌號碼「1253」。 |
language |
BCP-47 語言代碼。如果元件名稱未與語言 (例如門牌號碼) 建立關聯,就不會顯示。 |
ConfirmationLevel
確認層級的不同可能值。
列舉 | |
---|---|
CONFIRMATION_LEVEL_UNSPECIFIED |
預設值。這個值未使用。 |
CONFIRMED |
我們可驗證該元件是否存在,且與地址的其他內容一致。 |
UNCONFIRMED_BUT_PLAUSIBLE |
我們無法確認這個元件,但它可能存在。例如,在街道上,門牌號碼位於已知有效範圍內,但具體門牌號碼不明。 |
UNCONFIRMED_AND_SUSPICIOUS |
這個元件未經確認,可能有誤。例如,不符合地址其餘部分的鄰里。 |
Geocode
包含輸入內容經過地理編碼後的地點資訊。
JSON 表示法 |
---|
{ "location": { object ( |
欄位 | |
---|---|
location |
輸入內容的地理編碼位置。 建議您使用地點 ID,而非地址、經緯度座標或 Plus Code。在規劃路線或計算行車路線時使用座標,系統一律會將點對齊最接近該座標的道路。這條路可能無法快速或安全地通往目的地,也可能不在房源附近。此外,當位置經過反向地理編碼後,傳回的地址不一定會與原始地址相符。 |
plus |
與 |
bounds |
已編碼地點的邊界。 |
feature |
經過地理編碼的地點大小,以公尺為單位。這是另一種評估經地理編碼位置粗略程度的方式,但以實際大小而非語義意義為準。 |
place |
這個輸入地理編碼的目標地點的 PlaceID。 如要進一步瞭解地點 ID,請參閱這篇文章。 |
place |
輸入內容經地理編碼後的地點類型。例如: |
LatLng
代表經緯度組合的物件。以一對雙精準數表示經度度數和緯度度數。除非另有指定,否則這個物件必須符合 WGS84 標準。此外,值必須在正規化範圍內。
JSON 表示法 |
---|
{ "latitude": number, "longitude": number } |
欄位 | |
---|---|
latitude |
緯度度數,必須介於 [-90.0, +90.0] 的範圍之間。 |
longitude |
經度度數,必須介於 [-180.0, +180.0] 的範圍之間。 |
PlusCode
Plus Code (http://plus.codes) 是一種位置參照,有兩種格式:全球代碼定義 14 公尺 x 14 公尺 (1/8000 度) 或更小的矩形,複合代碼則會將前置字元替換為參照位置。
JSON 表示法 |
---|
{ "globalCode": string, "compoundCode": string } |
欄位 | |
---|---|
global |
地點的全球 (完整) 代碼,例如「9FWM33GV+HQ」,代表 1/8000 度 x 1/8000 度 (約 14 公尺 x 14 公尺) 的面積。 |
compound |
地點的複合代碼,例如「33GV+HQ, Ramberg, Norway」,包含全球代碼的後置字串,並將前置字串替換為參考實體的格式化名稱。 |
可視區域
經緯度可視區域,以兩個對角相反的 low
和 high
點表示。系統會將可視區域視為封閉區域,也就是包含界線的邊界。緯度範圍必須介於 -90 到 90 度之間 (含首尾),經度範圍則需介於 -180 到 180 度之間 (含首尾)。各種情況包括:
如果
low
=high
,可視區域就會包含該單一點。如果
low.longitude
>high.longitude
,經度範圍會反轉 (可視區域會跨越 180 度經線)。如果
low.longitude
= -180 度,且high.longitude
= 180 度,則可視區域會包含所有經度。如果
low.longitude
= 180 度且high.longitude
= -180 度,則經度範圍為空白。如果
low.latitude
>high.latitude
,緯度範圍是空的。
low
和 high
都必須填入資料,且代表的方塊不得為空白 (如上述定義所述)。空白的檢視區會導致錯誤。
舉例來說,這個視區會完全包含紐約市:
{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }
JSON 表示法 |
---|
{ "low": { object ( |
欄位 | |
---|---|
low |
必要欄位。可視區域的低點。 |
high |
必要欄位。可視區域的高點。 |
AddressMetadata
地址的中繼資料。metadata
不保證會為傳送至 Address Validation API 的每個地址完整填入資料。
JSON 表示法 |
---|
{ "business": boolean, "poBox": boolean, "residential": boolean } |
欄位 | |
---|---|
business |
表示這是商家地址。如果未設定,則表示值不明。 |
po |
表示郵政信箱的地址。如果未設定,則表示值不明。 |
residential |
表示這是住家地址。如未設定,表示該值不明。 |
UspsData
地址的 USPS 資料。uspsData
不保證會為每個傳送至 Address Validation API 的美國或波多黎各地址完整填入資料。如果您將 uspsData 用於回應的主要部分,建議您在回應中整合備用地址欄位。
JSON 表示法 |
---|
{
"standardizedAddress": {
object ( |
欄位 | |
---|---|
standardized |
USPS 標準格式地址。 |
delivery |
2 位數交貨地點代碼 |
delivery |
運送地點檢查碼。這個號碼會加到機器掃描郵件中的 delivery_point_barcode 結尾。將 delivery_point_barcode、deliveryPointCheckDigit、郵遞區號和郵遞區號 + 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 (Private Mail Box) 單位指標。 |
pmb |
PMB (Private Mail Box) 號碼 |
address |
與輸入地址相符的地址記錄類型。
|
default |
這個指標表示系統找到預設地址,但存在更明確的位址。 |
error |
USPS 資料擷取錯誤訊息。當 USPS 偵測到人為建立的地址,系統就會暫停處理。 發生這項錯誤時,系統可能不會填入 USPS 資料欄位。 |
cass |
表示要求已由 CASS 處理的指標。 |
UspsAddress
USPS 表示美國地址。
JSON 表示法 |
---|
{ "firstAddressLine": string, "firm": string, "secondAddressLine": string, "urbanization": string, "cityStateZipAddressLine": string, "city": string, "state": string, "zipCode": string, "zipCodeExtension": string } |
欄位 | |
---|---|
first |
第一行地址。 |
firm |
公司名稱。 |
second |
第二行地址。 |
urbanization |
波多黎各都市化名稱。 |
city |
城市 + 州 + 郵遞區號。 |
city |
城市名稱。 |
state |
2 個字母的州代碼。 |
zip |
郵遞區號,例如 10009。 |
zip |
4 位數郵遞區號擴充碼,例如 5023。 |