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 phần nội dung phản hồi dưới dạng một đối tượng JSON chứa hai 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 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ả của quá trình xác thực địa chỉ và phải là thuộc tính đầu tiên được đá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ụ: nội dung 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
}

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

Độ 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 đặc điểm 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 chi tiết sau:

• inputGranularity – Mô tả mức độ chi tiết được ghi lại từ địa chỉ được gửi đến Address Validation API. Mức độ chi tiết của địa chỉ trong yêu cầu ảnh hưởng đến mức độ chi tiết của địa chỉ trong phản hồi xác thực. Ví dụ: địa chỉ có inputGranularity dưới PREMISE thường không dẫn đến validationGranularity đến cấp PREMISE.
• validationGranularity – Cấp độ 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 một địa chỉ chất lượng có thể được 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ụ: bản ghi của Google có thể cho biết có số căn hộ nhưng không cho biết 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 geocodeGranularityisPREMISE`.

Địa chỉ đầy đủ

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 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
}

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

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

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

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

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 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ỉ, các phần bị thay thế không chính xác và các phần bị thiếu được suy luận.

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.

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. 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.

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 API Xác thực địa chỉ 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.

Thuộc tính uspsData

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