Để xác thực địa chỉ bằng API Xác thực địa chỉ, hãy gọi phương thức validateAddress (REST) hoặc phương thức ConfirmAddress (gRPC). Tài liệu này sử dụng REST cho các ví dụ, nhưng cách tiếp cận cũng tương tự như với gRPC.
Sau khi xác thực một địa chỉ, bạn có thể tuỳ ý trả về thông tin cho Google về kết quả xác thực địa chỉ bằng cách gọi phương thức provideValidationFeedback (REST) hoặc phương thức ProvideValidationFeedback (gRPC). Để biết thông tin và ví dụ, hãy xem phần Cung cấp ý kiến phản hồi về việc xác thực địa chỉ.
Yêu cầu xác thực địa chỉ
Xác thực địa chỉ bằng cách gửi yêu cầu POST đến phương thức validateAddress:
https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY
Chuyển nội dung JSON đến yêu cầu xác định địa chỉ cần xác thực:
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"
Trường address trong nội dung yêu cầu, thuộc loại PostalAddress, phải chứa ít nhất một mục nhập trong addressLines.
Trường
regionCodelà không bắt buộc. Nếu bỏ qua, API sẽ dự đoán khu vực từ địa chỉ. Tuy nhiên, để có hiệu suất tốt nhất, bạn nên sử dụngregionCodenếu biết mã này. Để biết danh sách các khu vực được hỗ trợ, vui lòng xem các khu vực được hỗ trợ.Tổng độ dài của trường
addressđược giới hạn ở 280 ký tự.
Bật CASSTM (không bắt buộc) khi xác thực địa chỉ
United States Postal Service® (USPS®)1 duy trì Hệ thống hỗ trợ về độ chính xác của mã hoá (CASSTM) để hỗ trợ và chứng nhận các nhà cung cấp dịch vụ xác thực địa chỉ. Một dịch vụ CASS được chứng nhậnTM, chẳng hạn như API xác thực địa chỉ, đã được xác nhận về khả năng điền thông tin còn thiếu trong một địa chỉ, chuẩn hoá và cập nhật địa chỉ đó để cung cấp cho bạn địa chỉ mới nhất và chính xác nhất.
Riêng đối với khu vực "US" và "PR", bạn có thể tuỳ ý bật tính năng xử lý CASS bằng cách đặt enableUspsCass thành true trong nội dung yêu cầu.
Để có kết quả tốt nhất khi sử dụng CASS, hãy cung cấp địa chỉ bao gồm số nhà và số nhà cùng với thành phố, tiểu bang và mã bưu chính:
{
"address": {
"regionCode": "US",
"locality": "Mountain View",
"administrativeArea": "CA",
"postalCode": "94043",
"addressLines": ["1600 Amphitheatre Pkwy"]
},
"enableUspsCass": true
}
Bạn cũng có thể chỉ định địa chỉ đầy đủ dưới dạng hai chuỗi trong mảng addressLines:
{
"address": {
"regionCode": "US",
"addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
},
"enableUspsCass": true
}
Phản hồi xác thực địa chỉ
Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái HTTP 200 OK và một nội dung phản hồi chứa thông tin về địa chỉ đã xác thực.
Trường result của phản hồi chứa đối tượng ValidationResult. Đối tượng này bao gồm:
Trường
addressthuộc loại Address (Địa chỉ) chứa thông tin chi tiết về địa chỉ.Trường
geocode, thuộc loại Mã địa lý, chứa thông tin mã địa lý cho địa chỉ.Trường
verdict, thuộc loại Kết quả, chứa kết quả xác thực địa chỉ và mã địa lý.Trường
metadatathuộc loại AddressMetadata, chứa siêu dữ liệu cho địa chỉ đó.Trường
uspsData, thuộc loại USPSData, chứa dữ liệu USPS cho địa chỉ. Dữ liệu này chỉ có sẵn cho các địa chỉ ở Hoa Kỳ và Puerto Rico.
Vì phản hồi sau đây chứa addressComplete được đặt thành true, nên phản hồi cho biết địa chỉ này hoàn toàn hợp lệ, vì vậy, bạn không cần phải xác thực thêm. Nếu phản hồi cho biết rằng một số phần của địa chỉ không hợp lệ, hãy nhắc người dùng kiểm tra và xác nhận mục đã nhập địa chỉ của họ.
{
"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"
}
Xác thực địa chỉ đã cập nhật
Trong một số trường hợp, bạn có thể phải thực hiện nhiều lệnh gọi đến API xác thực địa chỉ cho một địa chỉ. Ví dụ: người dùng có thể thay đổi hoặc sửa địa chỉ sau khi thấy kết quả của lần xác thực đầu tiên. Sau đó, bạn sẽ thực hiện lần xác thực thứ hai đối với địa chỉ đã cập nhật.
Mỗi lệnh gọi API Xác thực địa chỉ sẽ trả về một giá trị duy nhất trong trường responseId của phản hồi. Nếu một địa chỉ mà bạn đang cố gắng xác thực cần được xác thực lại, hãy chuyển responseId từ phản hồi xác thực đầu tiên trong trường previousResponseId cho tất cả các yêu cầu tiếp theo đến API xác thực địa chỉ.
Bằng cách đưa trường previousResponseId vào yêu cầu mới, bạn có thể giúp chúng tôi cải thiện độ chính xác tổng thể của API.
Ví dụ: phản hồi hiển thị ở trên bao gồm trường responseId:
"responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
Sau đó, bạn muốn xác thực lại địa chỉ bằng một thay đổi đối với số đường phố từ 1600 thành 1500. Khi bạn xác thực lại địa chỉ, hãy thêm trường previousResponseId có giá trị của responseId từ phản hồi đầu tiên:
{
"address": {
"regionCode" : "US",
"locality" : "Mountain View",
"addressLines" : ["1500 Amphitheatre Pkwy"]
},
"previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}
Đối với yêu cầu sử dụng CASS:
{
"address": {
"regionCode" : "US",
"locality" : "Mountain View",
"addressLines" : ["1500 Amphitheatre Pkwy"]
},
"previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
"enableUspsCass": true
}
Kết quả của mỗi lệnh gọi tiếp theo sẽ trả về một giá trị mới trong trường responseId. Tuy nhiên, hãy tiếp tục truyền giá trị của responseId từ phản hồi đầu tiên trong trường previousResponseId trên tất cả các lệnh gọi tiếp theo để cập nhật địa chỉ.
Xử lý lỗi
API xác thực địa chỉ sẽ trả về thông báo lỗi trong quá trình phản hồi lệnh gọi phương thức. Ví dụ: nếu bạn bỏ qua khoá API khỏi yêu cầu, phương thức này sẽ trả về:
{
"error": {
"code": 403,
"message": "The request is missing a valid API key.",
"status": "PERMISSION_DENIED"
}
}
Nếu bạn bỏ qua một tham số nội dung bắt buộc, chẳng hạn như addressLines, phương thức này sẽ trả về:
{
"error": {
"code": 400,
"message": "Address lines missing from request.",
"status": "INVALID_ARGUMENT"
}
}
Để biết thêm thông tin về lỗi và cách xử lý lỗi, hãy xem bài viết Lỗi.
-
Google Maps Platform là Bên được cấp phép không độc quyền của Hoa Kỳ Postal Service®. (Các) nhãn hiệu sau thuộc sở hữu của United States Postal Service® và được sử dụng với sự cho phép: United States Postal Service®, CASSTM, CASS khóaTM. ↩