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 nội dung phản hồi dưới dạng JSON đối tượng 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ả 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ỉ. Tài sản 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, 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.

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

Mức độ chi tiết về đị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ý. Đặc điểm về địa chỉ trong Phản hồi của validationGranularity là tín hiệu quan trọng để cho biết một địa chỉ có thể giao hà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 thu thập được qua được gửi đến API xác thực địa chỉ. Cấp 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 bên dưới PREMISE bên dưới cấp độ thường không dẫn đến validationGranularity thành PREMISE cấp độ.
• 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ó khả năng phân phối được.
• geocodeGranularity — Mô tả mức độ chi tiết của mã địa lý được 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 số đó một căn hộ nhất định trong một tổ hợp chung cư lớn. Trong trường hợp đó, validationGranularity là SUB_PREMISE nhưng là geocodeGranularityisPREMISE".

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 địa chỉ chất lượng cao, nghĩa là cụ thể là không bị thiếu địa chỉ nào, thành phần 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, 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ể xảy ra cho biết sự cố với thành phần địa chỉ, hoặc các điều chỉnh cho chú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ỉ chưa được xác nhận thành phần và trường addressComplete bị thiếu:

"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ý mà bạn cung cấp trong yêu cầu, cùng với thông tin tóm tắt về địa chỉ ở cấp thành phần, bao gồm các phần địa chỉ sai chính tả, thay thế các phần không chính xác và được suy luận là bị thiếu phụ kiệ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 các thành phần) của địa chỉ mà API xác thực địa chỉ đã được xử lý. API xác định từng thành phần cung cấp theo tên, loại và mức độ 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 đầu vào của bạn. 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.

Thuộc tính metadata

Thuộc tính này có thể không được điền sẵn cho mọi địa chỉ do Address Validation API 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.

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, nó không đảm bảo sẽ được điền đầy đủ cho mọi địa chỉ được xác thực dịch vụ. Do đó, bạn không nên coi thuộc tính này là duy nhất có nghĩa là xác thực địa chỉ, nhưng thay vào đó hãy kiểm tra verdict và address.