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

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": {
    // 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 bài viết Xử lý các địa chỉ đã cập nhật.

Thuộc tính verdict

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 tạo 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 và thuộc tính này sẽ 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 Kết quả trong hướng dẫn tham khảo.

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

Độ chi tiết của địa chỉ là mức độ chi tiết dùng để xác định tính cụ thể của một địa chỉ hoặc mã địa lý. Độ cụ thể về địa chỉ trong phản hồi validationGranularity là một tín hiệu quan trọng về việc một địa chỉ có thể phân phối hay không.

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

  • 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ỉ. Cấp chi tiết địa chỉ trong yêu cầu ảnh hưởng đến mức độ chi tiết địa chỉ trong phản hồi xác thực. Ví dụ: một địa chỉ có inputGranularity thấp hơn PREMISE thấp hơn cấp độ thường không dẫn đến việc validationGranularity chuyển sang 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 các 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ó thể gửi được.
  • geocodeGranularity — Mô tả mức độ chi tiết của mã địa lý liên kết với địa chỉ. Ví dụ: bản ghi 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 phức hợp căn hộ lớn. Trong trường hợp đó, validationGranularity là SUB_PREMISE nhưng là geocodeGranularityisPREMISE".
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 một tín hiệu cho một địa chỉ chất lượng cao, tức là cụ thể là thuộc tính đó không bị thiếu, chưa được giải quyết hoặc thành phần không mong muốn:

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

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

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ể xảy ra cho biết sự cố với các thành phần địa chỉ hoặc các điều chỉnh đối với các trường đó, chẳng hạn như các thành phần địa chỉ được suy luận hoặc bị 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à trường addressComplete bị thiếu:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
Xem Kết quả trong hướng dẫn tham khảo.

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

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 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 địa chỉ sai chính tả, thay thế các phần không chính xác và suy ra các phần bị thiếu.

Hãy 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 cá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à mức độ xác nhận.

Hãy xem addressComponent trong hướng dẫn tham khảo.

Thuộc tính geocode

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. Cơ sở lưu trú này cung cấp thông tin chi tiết về vị trí đó, chẳng hạn như mã địa điểm.

Hãy xem Geocode trong hướng dẫn tham khảo.

Thuộc tính metadata

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

Xem Phạm vi API xác thực địa chỉ và tài liệu tham khảo về Address metadata.

Thuộc tính uspsData

Thuộc tính 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, việc này không đảm bảo sẽ được điền đầy đủ dữ liệu 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 dưới dạng giá trị duy nhất để 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à tài liệu tham khảo về UspsData.
Trước
Gửi yêu cầu xác thực địa chỉ
Tiếp
Xây dựng logic xác thực