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

Phản hồi của Address Validation API chứa các thuộc tính cấp cao nhất sau:

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // 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"
}

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ỉ. 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ụ: phần 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ề các trường sau cho yêu cầu cụ thể này:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

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 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ý. Mức độ cụ thể của địa chỉ trong phản hồi của validationGranularity là một tín hiệu quan trọng 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ỉ được gửi đến API Xác thực địa chỉ trong Maps JavaScript. 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 mức PREMISE thường không dẫn đến validationGranularity đến mức PREMISE.
• validationGranularity — Mức độ chi tiết mà tính năng Xác thực địa chỉ trong API JavaScript của Maps 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 PREMISE hoặc SUB_PREMISE cho biết địa chỉ có chất lượng tốt và có thể giao hàng.
• 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 một 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 chung cư lớn. Trong trường hợp đó, validationGranularity là SUB_PREMISE nhưng geocodeGranularity là PREMISE.

Mức độ đầ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, 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, chưa được phân giải hoặc có 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 vấn đề với các thành phần địa chỉ hoặc điều chỉnh cho các thành phần đó, chẳng hạn như 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à thiếu trường addressComplete:

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

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

Trường possibleNextAction cung cấp thông tin tóm tắt diễn giải về phản hồi của API, nhằm hỗ trợ xác định hành động tiềm năng tiếp theo cần thực hiện. Trường này được lấy từ các trường khác trong phản hồi của API và không được coi là đảm bảo về độ chính xác hoặc khả năng gửi của địa chỉ.

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 viết sai 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.

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à tính năng Xác thực địa chỉ trong Maps JavaScript API đã xử lý. API xác định từng trường thành phần được 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 đị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 cho mọi địa chỉ được xử lý bằng tính năng Xác thực địa chỉ trong API JavaScript của Maps, nhưng 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 có gì đảm bảo rằng trường này sẽ được điền đầy đủ cho mọi địa chỉ được 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 tiện duy nhất để xác thực địa chỉ, mà thay vào đó, hãy kiểm tra cả verdict và address.