Hiểu phản hồi cơ bản về việc xác thực địa chỉ

Lưu ý: Tài liệu này mô tả các phần tử cơ bản của một phản hồi xác thực địa chỉ cho một địa chỉ có chất lượng cao. Để được hướng dẫn về cách xử lý các trường hợp địa chỉ thực tế và xây dựng logic dựa trên các phản hồi phức tạp hơn, hãy xem phần Xây dựng logic xác thực.

Address Validation API cung cấp một nội dung phản hồi dưới dạng một đối tượng JSON chứa 2 thuộc tính cấp cao nhất:

• result, một đối tượng thuộc loại ValidationResult
• responseID

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

Tài liệu này tập trung vào đối tượng result. Để biết thông tin về responseID, hãy xem phần Xử lý địa chỉ đã cập nhật.

Thuộc tính verdict

Lưu ý quan trọng: Sử dụng thuộc tính verdict để xem thông tin tóm tắt cơ bản về chất lượng của địa chỉ.

Thuộc tính verdict tóm tắt kết quả xác thực địa chỉ và phải là thuộc tính đầu tiên cần đánh giá khi xây dựng logic kiểm tra địa chỉ. Thuộc tính này có thể trả về nhiều trường, tuỳ thuộc vào chất lượng của địa chỉ đầu ra. Ví dụ: sau đây cho thấy thuộc tính verdict của một địa chỉ có chất lượng tốt, trả về 4 trường cho yêu cầu cụ thể này:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true,
  "possibleNextAction": "ACCEPT"
}

Các phần sau đây tóm tắt tất cả các trường trong thuộc tính verdict.

Xem Verdict trong hướng dẫn tham khảo.

Hành động tiếp theo có thể thực hiện

Thuộc tính possibleNextAction cung cấp bản tóm tắt mang tính diễn giải về phần còn lại của phản hồi API, với mục tiêu là giúp bạn xác định xem có nên nhắc khách hàng xem xét hoặc chỉnh sửa địa chỉ của họ hay không. Hãy xem phần Tạo logic xác thực để biết thêm thông tin.

Độ chi tiết của địa chỉ

Mức độ chi tiết của địa chỉ đề cập đến mức độ chi tiết được dùng để xác định tính cụ thể của một địa chỉ hoặc mã địa lý. Mức độ cụ thể của địa chỉ trong phản hồi validationGranularity là một tín hiệu chính cho biết địa chỉ có thể giao hàng hay không.

Thuộc tính verdict trả về các tín hiệu chi tiết sau:

• inputGranularity – Mô tả mức độ chi tiết được ghi lại từ địa chỉ gửi đến Address Validation API. Mức độ chi tiết của địa chỉ trong yêu cầu sẽ ảnh hưởng đến mức độ chi tiết của địa chỉ trong phản hồi xác thực. Ví dụ: một địa chỉ có inputGranularity dưới PREMISE dưới cấp độ thường không dẫn đến validationGranularity đến cấp độ PREMISE.
• validationGranularity – Cấp độ chi tiết mà Address Validation API có thể xác thực đầy đủ địa chỉ. Trong hầu hết trường hợp, mức độ chi tiết là PREMISE hoặc SUB_PREMISE cho biết địa chỉ chất lượng có khả năng được giao hàng.
• geocodeGranularity – Mô tả mức độ chi tiết của mã địa lý được liên kết với địa chỉ. Ví dụ: hồ sơ của Google có thể cho biết sự tồn tại của một số căn hộ, nhưng không phải là vị trí chính xác của căn hộ cụ thể đó trong một khu chung cư lớn. Trong trường hợp đó, validationGranularity là SUB_PREMISE nhưng geocodeGranularityisPREMISE`.

Xem phần Mức độ chi tiết trong hướng dẫn tham khảo.

Tính đầy đủ của địa chỉ

Kết quả trả về thuộc tính addressComplete dưới dạng tín hiệu cho một địa chỉ chất lượng cao, tức là cụ thể là địa chỉ đó không có thành phần nào bị thiếu, chưa được phân giải hoặc không mong muốn:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true,
    "possibleNextAction": "ACCEPT"
}

Khi địa chỉ có các thành phần bị thiếu, chưa được phân giải hoặc không mong muốn, trường này sẽ được đặt thành false.

Lưu ý: Khi thuộc tính addressComplete không xuất hiện trong kết quả sau khi kiểm tra thủ công, giá trị của thuộc tính này là false. Tuỳ thuộc vào ngôn ngữ lập trình, bạn sẽ truy vấn kết quả cho sự hiện diện của thuộc tính addressComplete hoặc truy vấn trực tiếp thuộc tính này. Hãy xem phần Chất lượng địa chỉ bên dưới để biết ví dụ.

Hãy xem addressComplete trong phần Verdict và Địa chỉ trong hướng dẫn tham khảo.

Chất lượng địa chỉ

Một số trường có thể cho biết vấn đề với các thành phần địa chỉ hoặc các điều chỉnh đối với các thành phần đó, chẳng hạn như các thành phần địa chỉ bị thiếu hoặc được suy đoán. Ví dụ: thuộc tính verdict sau đây cho biết một địa chỉ có các thành phần chưa được xác nhận và thiếu trường addressComplete:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

Xem Verdict trong hướng dẫn tham khảo.

Các thuộc tính address và addressComponent

Lưu ý quan trọng: Sử dụng thuộc tính address để lấy định dạng địa chỉ. Hãy sử dụng thành phần phụ addressComponent để điều tra lỗi và cung cấp thông tin về những lỗi đó cho khách hàng. Tuy nhiên, đừng tạo chế độ tích hợp để dựa vào cấp độ xác nhận cụ thể cho các thành phần địa chỉ. Hãy xem phần Xây dựng logic xác thực để biết hướng dẫn về quy trình tích hợp.

Thuộc tính address cung cấp định dạng cho địa chỉ đã xử lý có trong yêu cầu, cùng với thông tin tóm tắt ở cấp thành phần của địa chỉ, bao gồm cả các phần bị lỗi chính tả của địa chỉ, các phần không chính xác đã được thay thế và các phần bị thiếu đã được suy luận.

Xem Address trong hướng dẫn tham khảo.

Thuộc tính addressComponent là một thành phần phụ của address, cung cấp danh sách chi tiết về các phần tử (hoặc thành phần) của địa chỉ mà Address Validation API đã xử lý. API này xác định từng trường thành phần theo tên, loại và cấp độ xác nhận.

Xem addressComponent trong hướng dẫn tham khảo.

Thuộc tính geocode

Lưu ý quan trọng: Sử dụng thuộc tính geocode để thuận tiện lấy mã địa lý hoặc mã địa điểm khi logic của bạn trước đây gọi Geocoding API.

Thuộc tính geocode cho biết vị trí được mã hoá địa lý liên kết với địa chỉ đầu vào. Thuộc tính này cung cấp thông tin chi tiết về chính vị trí đó, chẳng hạn như mã địa điểm.

Xem Geocode trong hướng dẫn tham khảo.

Thuộc tính metadata

Lưu ý quan trọng: Sử dụng thuộc tính metadata để xác định loại tài sản được liên kết với địa chỉ: địa chỉ nhà ở, hộp thư bưu điện hoặc địa chỉ doanh nghiệp.

Thuộc tính này có thể không được điền sẵn cho mọi địa chỉ mà Address Validation API xử lý, nhưng cho biết liệu địa chỉ đó thuộc loại địa chỉ nhà ở, địa chỉ doanh nghiệp hay hộp thư bưu điện.

Xem Phạm vi cung cấp của Address Validation API và thông tin tham khảo về Address metadata.

Thuộc tính uspsData

Lưu ý quan trọng: Sử dụng thuộc tính uspsData để nhận được mức độ tin cậy khi phân phối và các thông tin khác của USPS về địa chỉ tại Hoa Kỳ.

Thuộc tính này cung cấp thông tin hữu ích cho địa chỉ bưu điện ở Hoa Kỳ. Tuy nhiên, không có gì đảm bảo rằng mọi địa chỉ được dịch vụ xác thực đều được điền đầy đủ. Vì lý do đó, bạn không nên chỉ dựa vào thuộc tính này để xác thực địa chỉ, mà thay vào đó, hãy kiểm tra cả verdict và address.

Hãy xem bài viết Xử lý địa chỉ ở Hoa Kỳ và thông tin tham khảo về UspsData.