如要使用 Address Validation API 驗證地址，請呼叫 validateAddress 方法 (REST) 或 ValidateAddress 方法 (gRPC)。本說明文件使用 REST 做為範例，但這個方法與 gRPC 類似。
驗證地址後，您可以選擇呼叫 provideValidationFeedback 方法 (REST) 或 ProvideValidationFeedback 方法 (gRPC)，將地址驗證結果相關資訊傳回 Google。如需詳細資訊和範例，請參閱「提供地址驗證意見回饋」。
地址驗證要求
將 POST 要求傳送至 validateAddress 方法，即可驗證地址：
https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY
將 JSON 主體傳送至要求定義要驗證的地址：
curl -X POST -d '{
"address": {
"regionCode": "US",
"locality": "Mountain View",
"addressLines": ["1600 Amphitheatre Pkwy"]
}
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY"
要求主體 (類型為 PostalAddress) 中的 address 欄位必須包含至少一個 addressLines 項目。
regionCode為選填欄位，如果省略此屬性，API 會從地址推測出區域。不過，為獲得最佳效能，建議您加入regionCode(如果知道的話)。如需支援地區清單，請參閱支援地區。address欄位的總長度上限為 280 個半形字元。
在驗證地址時視需要啟用 CASSTM
美國郵政署 (USPS®)1 負責維護編碼準確度支援系統 (CASSTM)，以便支援並認證地址驗證服務供應商。CASS CertifiedTM 服務 (例如 Address Validation API) 已確認可以填入地址缺少的資訊、將地址標準化，並提供更新，提供最新且最準確的地址。
針對「US」和「PR」區域，您可以選擇在要求主體中將 enableUspsCass 設為 true，以啟用 CASS 處理。
為確保使用 CASS 時能獲得最佳效果，請提供包含街道和門牌號碼的地址，以及城市、州/省和郵遞區號：
{
"address": {
"regionCode": "US",
"locality": "Mountain View",
"administrativeArea": "CA",
"postalCode": "94043",
"addressLines": ["1600 Amphitheatre Pkwy"]
},
"enableUspsCass": true
}
您也可以在 addressLines 陣列中將完整地址指定為兩個字串：
{
"address": {
"regionCode": "US",
"addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
},
"enableUspsCass": true
}
地址驗證回應
如果要求成功，伺服器會傳回 HTTP 200 OK 狀態碼，以及含有已驗證地址相關資訊的回應主體。
回應的 result 欄位包含 ValidationResult 物件。此物件包括：
類型為 Address 的
address欄位，包含地址的詳細資訊。類型為地理編碼的
geocode欄位，包含地址的地理編碼資訊。類型為 Verdict 的
verdict欄位，包含地址驗證和地理編碼結果。類型的
metadata欄位 (屬於 AddressMetadata 類型)，包含位址的中繼資料。類型為 USPSData 的
uspsData欄位，包含地址的 USPS 資料。這項資料僅適用於美國和波多黎各的地址。
由於下列回應包含設為 true 的 addressComplete，因此回應表示這個地址完全有效，因此不需要進一步驗證。如果回應指出地址的某些部分無效，請提示使用者檢查並確認地址輸入資料。
{
"result": {
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true,
"hasInferredComponents": true
},
"address": {
"formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
"postalAddress": {
"regionCode": "US",
"languageCode": "en",
"postalCode": "94043-1351",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1600 Amphitheatre Pkwy"
]
},
"addressComponents": [
{
"componentName": {
"text": "1600",
"languageCode": "en"
},
"componentType": "street_number",
"confirmationLevel": "CONFIRMED"
},
{
"componentName": {
"text": "Amphitheatre Parkway",
"languageCode": "en"
},
"componentType": "route",
"confirmationLevel": "CONFIRMED"
},
{
"componentName": {
"text": "Mountain View",
"languageCode": "en"
},
"componentType": "locality",
"confirmationLevel": "CONFIRMED"
},
{
"componentName": {
"text": "USA",
"languageCode": "en"
},
"componentType": "country",
"confirmationLevel": "CONFIRMED"
},
{
"componentName": {
"text": "94043"
},
"componentType": "postal_code",
"confirmationLevel": "CONFIRMED",
"inferred": true
},
{
"componentName": {
"text": "CA",
"languageCode": "en"
},
"componentType": "administrative_area_level_1",
"confirmationLevel": "CONFIRMED",
"inferred": true
},
{
"componentName": {
"text": "1351"
},
"componentType": "postal_code_suffix",
"confirmationLevel": "CONFIRMED",
"inferred": true
}
]
},
"geocode": {
"location": {
"latitude": 37.4223878,
"longitude": -122.0841877
},
"plusCode": {
"globalCode": "849VCWC8+X8"
},
"bounds": {
"low": {
"latitude": 37.4220699,
"longitude": -122.084958
},
"high": {
"latitude": 37.4226618,
"longitude": -122.0829302
}
},
"featureSizeMeters": 116.538734,
"placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g",
"placeTypes": [
"premise"
]
},
"metadata": {
"business": false,
"poBox": false
},
"uspsData": {
"standardizedAddress": {
"firstAddressLine": "1600 AMPHITHEATRE PKWY",
"cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
"city": "MOUNTAIN VIEW",
"state": "CA",
"zipCode": "94043",
"zipCodeExtension": "1351"
},
"deliveryPointCode": "00",
"deliveryPointCheckDigit": "0",
"dpvConfirmation": "Y",
"dpvFootnote": "AABB",
"dpvCmra": "N",
"dpvVacant": "N",
"dpvNoStat": "Y",
"carrierRoute": "C909",
"carrierRouteIndicator": "D",
"postOfficeCity": "MOUNTAIN VIEW",
"postOfficeState": "CA",
"fipsCountyCode": "085",
"county": "SANTA CLARA",
"elotNumber": "0103",
"elotFlag": "A",
"addressRecordType": "S"
}
},
"responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}
驗證更新後的地址
在某些情況下，您可能需要對單一地址呼叫 Address Validation API。舉例來說，使用者看到第一次驗證的結果後，可能會變更或更正自己的地址。然後對更新後的地址執行第二次驗證。
每個 Address Validation API 呼叫會在回應的 responseId 欄位中傳回不重複的值。如果您想驗證的地址需要重新驗證，請將「所有」後續要求從 previousResponseId 欄位中的「第一個」驗證回應傳遞至 Address Validation API。responseId
在新要求中加入 previousResponseId 欄位，您就能協助我們改善 API 的整體準確率。
舉例來說，上述回應包含 responseId 欄位：
"responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
然後，您想將門牌號碼從 1600 變更為 1500 後重新驗證地址。重新驗證位址時，請加入 previousResponseId 欄位，並將從第一個回應中取得的 responseId 值加入：
{
"address": {
"regionCode" : "US",
"locality" : "Mountain View",
"addressLines" : ["1500 Amphitheatre Pkwy"]
},
"previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}
針對使用 CASS 的要求：
{
"address": {
"regionCode" : "US",
"locality" : "Mountain View",
"addressLines" : ["1500 Amphitheatre Pkwy"]
},
"previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
"enableUspsCass": true
}
每個後續呼叫的結果都會在 responseId 欄位中傳回新值。不過，在後續對地址進行更新的所有呼叫中，繼續透過 previousResponseId 欄位中的「第一個」回應傳送 responseId 的值。
處理錯誤
Address Validation API 會在方法呼叫回應中傳回錯誤訊息。舉例來說，如果您省略要求中的 API 金鑰，此方法會傳回：
{
"error": {
"code": 403,
"message": "The request is missing a valid API key.",
"status": "PERMISSION_DENIED"
}
}
如果您省略必要的主體參數 (例如 addressLines)，這個方法會傳回：
{
"error": {
"code": 400,
"message": "Address lines missing from request.",
"status": "INVALID_ARGUMENT"
}
}
如要進一步瞭解錯誤和錯誤處理機制，請參閱錯誤一文。
-
Google 地圖平台是美國郵政服務® 的非專屬被授權人。下列商標由美國郵政服務® 擁有，且經許可使用：United Postal Service®、CASSTM、CASS CertifiedTM。↩