- HTTP 要求
- 要求主體
- 回應主體
- PostalAddress
- LanguageOptions
- ValidationResult
- 判定結果
- 精細程度
- 地址
- AddressComponent
- 「ComponentName」ComponentName
- ConfirmationLevel
- 地理編碼
- LatLng
- PlusCode
- 可視區域
- AddressMetadata
- UspsData
- UspsAddress
驗證地址。
HTTP 要求
POST https://addressvalidation.googleapis.com/v1:validateAddress
這個網址使用 gRPC 轉碼語法。
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{ "address": { object ( |
欄位 | |
---|---|
address |
必要欄位。要驗證的地址。未設定格式的地址應透過 這項輸入欄位中的欄位總長度不得超過 280 個半形字元。 支援的地區請參閱這裡。 輸入地址中的 Address Validation API 會忽略 |
previousResponseId |
首次地址驗證要求時,這個欄位必須留空。如果需要更多要求才能完整驗證單一地址 (例如,若使用者在初始驗證後所做的變更需要重新驗證),則每個後續要求都必須在驗證序列中第一個回應內,將 |
enableUspsCass |
啟用 USPS CASS 相容模式。這項操作只會影響 建議您使用元件化的 |
languageOptions |
選用設定。預先發布版:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明。 啟用 Address Validation API,在回應中加入其他資訊。 |
sessionToken |
選用設定。用於識別計費 Autocomplete 工作階段的字串。必須是網址和檔案名稱安全 Base64 字串,長度上限為 36 個 ASCII 字元。否則系統會傳回 INVALID_UNIT 錯誤。 工作階段從使用者提出 Autocomplete 查詢時起算,直到使用者選取地點,並呼叫 Place Details 或 Address Validation 時結束。每個工作階段可包含多個 Autocomplete 查詢,後面接著一個 Place Details 或 Address Validation 要求。工作階段內每個要求使用的憑證,必須隸屬於同一個 Google Cloud 控制台專案。工作階段結束後,符記就會失效;應用程式必須為每個工作階段產生新的符記。如果省略 注意:Address Validation 僅適用於搭配 Autocomplete (New) API 的工作階段,而非 Autocomplete API。詳情請參閱 https://developers.google.com/maps/documentation/places/web-service/session-pricing。 |
回應主體
地址驗證要求的回應。
如果成功,回應主體即會包含具有以下結構的資料:
JSON 表示法 |
---|
{
"result": {
object ( |
欄位 | |
---|---|
result |
地址驗證的結果。 |
responseId |
用於識別此回應的 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 |
|
regionCode |
選用設定。地址所在國家/地區的 CLDR 地區代碼。詳情請參閱 https://cldr.unicode.org/ 和 https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html。例如:瑞士的字為「CH」。如未提供區碼,系統將從地址推斷。為獲得最佳效能,建議您加入區碼 (如果知道的話)。區域不一致或重複可能會導致效能不佳,例如,如果 |
languageCode |
輸入地址中的語言代碼僅供日後使用,現已遭到忽略。API 會以適當語言傳回地址所在位置的地址。 |
postalCode |
選用設定。地址的郵遞區號。並非所有國家/地區都使用郵遞區號或要求必須填寫郵遞區號,不過在使用郵遞區號時,可能會對地址其他部分觸發額外的驗證作業 (例如美國對州/郵遞區號的驗證)。 |
sortingCode |
選用設定。國家/地區專屬的其他分類代碼。大多數國家/地區並不使用這個代碼。在使用分類代碼的國家/地區中,這個值為與「CEDEX」相似的字串,後面選擇性加上一個數字 (例如「CEDEX 7」),或是只有單一數字,並用來表示「區段代碼」(牙買加)、「寄送區域指示碼」(馬拉威) 或「郵局指示碼」(如象牙海岸)。 |
administrativeArea |
選用設定。最高行政區,用於國家/地區的郵遞地址。例如,此值可以是州、省或縣。以西班牙為例來具體說明,此欄位的值為省,而非自治區 (例如「巴塞隆納」省,而不是「加泰隆尼亞」自治區)。許多國家/地區的郵寄地址並沒有使用行政區。例如,就瑞士而言,該欄位應該留空不填。 |
locality |
選用設定。一般是指地址的縣市/鄉鎮部分。例如:美國城市、義大利市鎮、英國郵鎮。如為未明確定義縣市或其縣市不適用此結構的地區,請將 locality 留白,改用 addressLines。 |
sublocality |
選用設定。地址的縣市以下行政區,例如社區、自治市鎮和區等。 |
addressLines[] |
必要欄位。非結構化的地址行,說明地址的低層級項目。 |
recipients[] |
請避免設定這個欄位。Address Validation API 目前並未使用。API 目前不會拒絕包含這個欄位集的要求,但資訊會遭到捨棄,且不會在回應中傳回。 |
organization |
請避免設定這個欄位。Address Validation API 目前並未使用。API 目前不會拒絕包含這個欄位集的要求,但資訊會遭到捨棄,且不會在回應中傳回。 |
LanguageOptions
預先發布版:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明。
啟用 Address Validation API,在回應中加入其他資訊。
JSON 表示法 |
---|
{ "returnEnglishLatinAddress": boolean } |
欄位 | |
---|---|
returnEnglishLatinAddress |
預覽:以英文傳回 |
ValidationResult
驗證地址的結果。
JSON 表示法 |
---|
{ "verdict": { object ( |
欄位 | |
---|---|
verdict |
整體判定結果標記 |
address |
地址本身 (而非地理編碼) 的資訊。 |
geocode |
取得地址地理編碼的位置和地點的相關資訊。 |
metadata |
與交付功能有關的其他資訊。我們不保證會針對傳送至 Address Validation API 的每個地址填入 |
uspsData |
USPS 提供的額外傳送性旗標。僅在 |
englishLatinAddress |
預先發布版:這項功能目前處於預先發布階段,也就是正式發布前的版本。正式發布前的產品和功能僅提供有限支援,且正式發布前產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明。 地址已翻譯成英文。 翻譯的地址無法做為 API 輸入內容重複使用。此服務會提供這些 API,讓使用者能使用其母語,確認或拒絕原先提供的地址驗證。 如果地址的一部分未提供英文翻譯,服務會以拉丁字母系統的替代語言傳回該部分地址。如需瞭解如何選擇替代語言,請參閱這裡的說明。如果地址其中一部分沒有使用拉丁字母語言之翻譯或音譯,服務會以與地址相關聯的當地語言傳回該部分。 使用 注意: |
評斷
地址驗證結果和地理編碼的概要總覽。
JSON 表示法 |
---|
{ "inputGranularity": enum ( |
欄位 | |
---|---|
inputGranularity |
輸入位址的精細程度。也就是剖析輸入地址的結果,並不會提供任何驗證信號。如要瞭解驗證信號,請參閱下方的 舉例來說,如果輸入的地址含有特定公寓號碼,則這裡的 |
validationGranularity |
API 可完整「驗證」validate地址的目標精細程度。舉例來說,如果 每個地址元件的驗證結果可在 |
geocodeGranularity |
這有時會與上方的 |
addressComplete |
如果沒有未解析的權杖、沒有非預期或遺漏的地址元件,系統會將地址視為「完整」。如未設定,則表示值為 |
hasUnconfirmedComponents |
至少有一個地址元件無法分類或驗證,詳情請參閱 |
hasInferredComponents |
系統判定至少有一個地址元件不是輸入的內容所推測 (已新增),詳情請參閱 |
hasReplacedComponents |
至少一個地址元件已被取代,詳情請參閱 |
精細程度
地址或地理編碼的各種精細程度。用來表示「地址」的精細程度時,這些值代表地址識別郵件目的地的精細程度。例如,「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 |
其餘的精細程度則會聚集在一起,因為這類項目無法傳送。 |
地址
處理後地址的詳細資料。後續處理包括修正地址中錯字的部分、替換不正確的部分,以及推斷缺漏的部分。
JSON 表示法 |
---|
{ "formattedAddress": string, "postalAddress": { object ( |
欄位 | |
---|---|
formattedAddress |
依地址所在區域的地址格式規則後處理的地址,格式為單行地址。 |
postalAddress |
後處理地址,以郵寄地址表示。 |
addressComponents[] |
未排序的清單。格式化地址的個別地址元件和驗證資訊。以便瞭解個別元件的驗證狀態。 地址元件不依特定順序排列。請勿假設清單中地址元件的順序。 |
missingComponentTypes[] |
應該出現在郵寄地址正確的郵寄地址中,「而且」無法推斷出類型的元件類型。 |
unconfirmedComponentTypes[] |
|
unresolvedTokens[] |
輸入裝置中無法解析的任何符記。例如,系統無法識別這個輸入內容是地址的有效部分 (例如輸入如「123235253253 Main St, San Francisco, CA, 94105」這類的輸入值),則未解析的符記看起來可能像 |
AddressComponent
代表地址元件,例如街道、城市或州/省。
JSON 表示法 |
---|
{ "componentName": { object ( |
欄位 | |
---|---|
componentName |
元件的名稱。 |
componentType |
地址元件的類型。如需可能的類型清單,請參閱「表 2:地點介面集服務傳回的其他類型」。 |
confirmationLevel |
表示我們確定元件正確無誤。 |
inferred |
表示輸入元件並非輸入內容的一部分,但我們根據地址位置推論此元件,且認為應提供完整的地址。 |
spellCorrected |
表示元件名稱中拼字有誤的修正。API 不一定會將拼字變體的不同變更標記出來,例如將「centre」變更為「center」時。這項功能有時也會標記常見的錯別字,例如將「Amphitheater Pkwy」變更為「Amphitheatre Pkwy」(英式開機車) 中。 |
replaced |
表示元件名稱已由完全不同的名稱取代,例如將錯誤的郵遞區號替換成地址正確的郵遞區號。這不是外觀的變更,而是輸入元件已變更。 |
unexpected |
表示指定區域的郵寄地址中沒有地址元件。我們只保留了因為內容為輸入內容的一部分。 |
ComponentName
元件名稱的包裝函式。
JSON 表示法 |
---|
{ "text": string, "languageCode": string } |
欄位 | |
---|---|
text |
名稱文字。例如「5th Avenue」代表街道名稱,「1253」代表門牌號碼。 |
languageCode |
BCP-47 語言代碼。如果元件名稱與語言 (例如門牌號碼) 沒有關聯,就不會顯示這個屬性。 |
ConfirmationLevel
確認等級的不同可能值。
列舉 | |
---|---|
CONFIRMATION_LEVEL_UNSPECIFIED |
預設值。未使用這個值。 |
CONFIRMED |
我們能夠確認這個元件確實存在,且在地址的其他部分具有意義。 |
UNCONFIRMED_BUT_PLAUSIBLE |
無法確認這個元件,但元件可能存在。例如街道中已知有效號碼範圍中的門牌號碼,且該號碼未知數。 |
UNCONFIRMED_AND_SUSPICIOUS |
這個元件未經確認,可能有誤。例如與地址其餘部分不符的社區。 |
Geocode
內含輸入地理編碼目的地的地點相關資訊。
JSON 表示法 |
---|
{ "location": { object ( |
欄位 | |
---|---|
location |
輸入內容的地理編碼位置。 比起使用地址、經緯度座標或加號,更建議使用地點 ID。使用座標來規劃行車路線或計算行車路線時,一律都會與最接近這些座標的道路對齊。這類道路不一定是即將或安全地導向目的地的道路,而且可能不在房源的存取點附近。此外,執行反向地理編碼時,我們也無法保證傳回的地址會與原始地址相符。 |
plusCode |
與 |
bounds |
地理編碼地點的邊界。 |
featureSizeMeters |
地理編碼地點的大小 (以公尺為單位)。對於地理編碼位置的粗略性,這是另一種測量方式,但是以實際大小而非語意含義。 |
placeId |
此輸入地理編碼目的地地點的 PlaceID。 如要進一步瞭解地點 ID,請參閱這篇文章。 |
placeTypes[] |
輸入進行地理編碼的地點類型。例如: |
LatLng
代表經緯度組合的物件。以一對雙精準數表示經度度數和緯度度數。除非另有指定,否則這個物件必須符合 WGS84 標準。此外,值必須在正規化範圍內。
JSON 表示法 |
---|
{ "latitude": number, "longitude": number } |
欄位 | |
---|---|
latitude |
緯度度數,必須介於 [-90.0, +90.0] 的範圍之間。 |
longitude |
經度度數,必須介於 [-180.0, +180.0] 的範圍之間。 |
PlusCode
Plus code (http://plus.codes) 是一種位置參照,格式有兩種:定義 14mx14m (度數 1/8000 度) 或小矩形代碼,以及複合代碼,將前置字串替換為參考位置。
JSON 表示法 |
---|
{ "globalCode": string, "compoundCode": string } |
欄位 | |
---|---|
globalCode |
地點的全球 (完整) 代碼,例如「9FWM33GV+HQ」,代表 1/8000 x 1/8000 度角 (約 14 x 14 公尺)。 |
compoundCode |
地點的複合代碼 (例如「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
地址的中繼資料。我們不保證會針對傳送至 Address Validation API 的每個地址填入 metadata
。
JSON 表示法 |
---|
{ "business": boolean, "poBox": boolean, "residential": boolean } |
欄位 | |
---|---|
business |
表示這是商家的地址。如未設定,則表示值不明。 |
poBox |
表示郵政信箱的地址。如未設定,則表示值不明。 |
residential |
表示這是居住地址。如未設定,則表示值不明。 |
UspsData
地址的 USPS 資料。我們不保證會為每個傳送至 Address Validation API 的美國或 PR 位址完整填入 uspsData
。如果您使用 uspsData 做為回應的主要部分,建議您在回應中整合備用地址欄位。
JSON 表示法 |
---|
{
"standardizedAddress": {
object ( |
欄位 | |
---|---|
standardizedAddress |
USPS 標準化位址。 |
deliveryPointCode |
2 位數寄送點代碼 |
deliveryPointCheckDigit |
寄送點檢查碼。這個號碼會加入用於自動掃描郵件,在 Delivery_point_barcode 末端所加上的號碼。將 delivery_point_barcode、deliveryPointCheckDigit、郵遞區號和 ZIP+4 的所有數字加在一起時,將得到可以用 10 除盡的數字。 |
dpvConfirmation |
DPV 確認要求的可能值。會傳回單一字元或未傳回任何值。
|
dpvFootnote |
運送點驗證的註腳。多個註腳可能會出現在同一個字串中。
|
dpvCmra |
指出地址是否為 CMRA (商用郵件接收代理商),這是供客戶接收郵件的私人企業。傳回單一字元。
|
dpvVacant |
這裡不開放嗎?傳回單一字元。
|
dpvNoStat |
這是否為沒有統計資料的地址或有效的地址?沒有統計資料地址,即非持續佔據的地址或 USPS 不提供服務的位址。傳回單一字元。
|
dpvNoStatReasonCode |
表示 NoStat 類型。以 int 傳回原因代碼。
|
dpvDrop |
這個標記表示郵件已傳送至某個網站上單一可接收的郵件。傳回單一字元。
|
dpvThrowback |
表示郵件未傳送至街道地址。傳回單一字元。
|
dpvNonDeliveryDays |
這個標記表示郵件未在同一週內每天傳送。傳回單一字元。
|
dpvNonDeliveryDaysValues |
識別未送達天數的整數。可以使用位元旗標進行審核:0x40 - 星期日是非放送日 0x20 – 星期一是 0x08 未放送日。星期三是非放送日 0x04 – 星期三是非放送日 0x04 – 星期四是非放送日 0x02 – 星期四是非放送日。 |
dpvNoSecureLocation |
這個標記表示門外有無障礙,但出於安全考量,系統不會留下包裹。傳回單一字元。
|
dpvPbsa |
表示地址與 PBSA 記錄相符。傳回單一字元。
|
dpvDoorNotAccessible |
旗標用於表示 USPS 無法親自寄門郵件的地址。傳回單一字元。
|
dpvEnhancedDeliveryCode |
表示地址的有效 DPV 傳回代碼。傳回單一字元。
|
carrierRoute |
貨運公司路線代碼。由 1 個字母前置字元和 3 位數路線指示器所組成的四個字元代碼。 前置字串:
|
carrierRouteIndicator |
貨運公司路線費率排序指標。 |
ewsNoMatch |
寄送地址可以比對,不過 EWS 檔案表示很快就會取得完全相符的地址。 |
postOfficeCity |
主要郵局城市。 |
postOfficeState |
主要的郵局狀態。 |
abbreviatedCity |
縮寫城市。 |
fipsCountyCode |
FIPS 縣市代碼。 |
county |
郡/縣名稱。 |
elotNumber |
加強行業 (eLOT) 編號。 |
elotFlag |
eLOT 遞增/遞減標記 (A/D)。 |
lacsLinkReturnCode |
LACSLink 傳回代碼。 |
lacsLinkIndicator |
LACSLink 指標。 |
poBoxOnlyPostalCode |
郵政信箱僅包含郵遞區號。 |
suitelinkFootnote |
這些註腳包括將街道或高樓層記錄與套房資訊進行比對的註腳。如果系統找到商家名稱相符,就會傳回次要號碼。
|
pmbDesignator |
PMB (私人信箱) 單元設計人員。 |
pmbNumber |
PMB (私人信箱) 號碼; |
addressRecordType |
與輸入地址相符的地址記錄類型。
|
defaultAddress |
這個指標代表已找到預設地址,但存在更明確的地址。 |
errorMessage |
USPS 資料擷取的錯誤訊息。如果因為偵測到人工建立地址而暫停 USPS 處理作業,系統就會填入這項資訊。 發生這個錯誤時,系統可能不會填入 USPS 資料欄位。 |
cassProcessed |
表示要求已處理 CASS 處理的指標。 |
UspsAddress
USPS 表示法。
JSON 表示法 |
---|
{ "firstAddressLine": string, "firm": string, "secondAddressLine": string, "urbanization": string, "cityStateZipAddressLine": string, "city": string, "state": string, "zipCode": string, "zipCodeExtension": string } |
欄位 | |
---|---|
firstAddressLine |
第一行地址。 |
firm |
公司名稱。 |
secondAddressLine |
第二行地址 |
urbanization |
波多黎各都市化名稱。 |
cityStateZipAddressLine |
城市 + 州/省 + 郵遞區號。 |
city |
城市名稱。 |
state |
由 2 個英文字母組成的州碼。 |
zipCode |
郵遞區號,例如 10009。 |
zipCodeExtension |
4 位數郵遞區號額外資訊,例如 5023。 |