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 thành phần cơ bản của phản hồi xác thực địa chỉ cho một địa chỉ có chất lượng cao. Để biết hướng dẫn về cách làm việc với các tình huống địa chỉ thực tế và xây dựng logic xung quanh 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.

API xác thực địa chỉ cung cấp một nội dung phản hồi dưới dạng đối tượng JSON chứa hai thuộc tính cấp cao nhất:

• result, đố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ý các địa chỉ đã cập nhật.

Thuộc tính verdict

Lưu ý quan trọng: Hãy sử dụng thuộc tính verdict để nhận thông tin tóm tắt cơ sở 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 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 là thuộc tính verdict của một địa chỉ có chất lượng tốt. Thuộc tính này trả về 4 trường cho yêu cầu cụ thể này:

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

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

Xem phần Kết quả trong hướng dẫn tham khảo.

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

Mức độ chi tiết của địa chỉ là 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ý. Tính cụ thể của địa chỉ trong phản hồi validationGranularity là một tín hiệu quan trọng để biết một địa chỉ có thể gửi được 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 thu thập từ địa chỉ được gửi đến API xác thực địa chỉ. Mức độ chi tiết về địa chỉ trong yêu cầu ảnh hưởng đến cấp chi tiết địa chỉ trong phản hồi xác thực. Ví dụ: địa chỉ có inputGranularity dưới PREMISE dưới cấp thường không dẫn đến validationGranularity thành cấp PREMISE.
• validationGranularity – Mức độ chi tiết mà API xác thực địa chỉ 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 phân phối.
• geocodeGranularity – Mô tả mức độ chi tiết của mã địa lý 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 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`.

Hãy xem phần Độ 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, nghĩa là cụ thể là địa chỉ đó không có thành phần nào bị thiếu, chưa được giải quyết hoặc không mong muốn:

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

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

Lưu ý: Khi thuộc tính addressComplete không xuất hiện trong kết quả kiểm tra thủ công, thì giá trị của thuộc tính đó là false. Tuỳ thuộc vào ngôn ngữ lập trình, bạn có thể truy vấn kết quả về 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 đó. Hãy xem phần Chất lượng địa chỉ bên dưới để biết ví dụ.

Xem addressComplete trong phần Kết quả và Địa chỉ trong hướng dẫn tham khảo.

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

Một số trường có thể có cho biết các 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ư thành phần địa chỉ được suy luận hoặc thiếu. 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à bị thiếu trường addressComplete:

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

Xem phần Kết quả trong hướng dẫn tham khảo.

Thuộc tính address và addressComponent

Lưu ý quan trọng: Hãy 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 để tìm hiểu lỗi và cung cấp thông tin về những lỗi đó cho khách hàng của bạn. Tuy nhiên, đừng xây dựng quá trình 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 bài viết Xây dựng logic xác thực để biết hướng dẫn tích hợp.

Thuộc tính address cung cấp định dạng cho địa chỉ đã xử lý được cung cấp trong yêu cầu, cùng với các bản tóm tắt ở cấp thành phần của địa chỉ, bao gồm cả các phần bị sai chính tả của địa chỉ, phần không chính xác được thay thế và phần bị thiếu theo suy đoá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 các phần tử (hoặc thành phần) của địa chỉ mà API xác thực địa chỉ đã xử lý. API xác định từng trường thành phần cung cấp 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: Hãy sử dụng thuộc tính geocode để thuận tiện cho việc lấy mã địa lý hoặc mã địa điểm khi logic của bạn trước đó đã gọi API mã hoá địa lý.

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ề 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: Hãy sử dụng thuộc tính metadata để xác định loại cơ sở lưu trú liên kết với địa chỉ: nhà ở, hộp thư bưu điện hoặc doanh nghiệp.

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

Xem Phạm vi bao phủ của API xác thực địa chỉ và tài liệu tham khảo cho 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 gửi thư và các thông tin chi tiết khác của USPS về các địa chỉ ở Hoa Kỳ.

Cơ sở lưu trú này cung cấp thông tin hữu ích về địa chỉ bưu chính tại Hoa Kỳ. Tuy nhiên, chúng tôi không đảm bảo sẽ điền đầy đủ thông tin cho mọi địa chỉ mà dịch vụ xác thực. Do đó, bạn không nên dựa vào thuộc tính này vì thuộc tính duy nhất có nghĩa là xác thực địa chỉ, mà thay vào đó hãy kiểm tra verdict và address.

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