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

API xác thực địa chỉ lấy một địa chỉ làm dữ liệu đầu vào. Sau đó, API sẽ trả về một phản hồi chứa:

  • Kết quả để xác thực toàn bộ địa chỉ và xác thực từng thành phần địa chỉ (số nhà, tên đường, thành phố, v.v.).

  • Một chuỗi duy nhất chứa địa chỉ đầy đủ do API xác định.

  • Các thuộc tính riêng lẻ chứa từng thành phần của địa chỉ do API xác định.

  • Danh sách các thành phần địa chỉ bị thiếu, bất kỳ thành phần địa chỉ nào chưa được xác nhận và bất kỳ thành phần địa chỉ nào không thể phân giải.

  • Mã địa lý của địa chỉ.

  • Đối với khu vực "US" và "PR", dữ liệu USPS cho địa chỉ.

Khi sử dụng phản hồi của API, bạn có thể đảm bảo địa chỉ đó tồn tại và đạt chất lượng cần thiết cho nhu cầu của bạn. Nếu phản hồi từ API cho biết địa chỉ không đầy đủ hoặc không chính xác, bạn có thể nhắc người dùng cập nhật địa chỉ. Sau khi người dùng hoàn tất quá trình cập nhật, hãy sử dụng API để xác thực địa chỉ đã cập nhật.

Tài liệu này mô tả cách xử lý phản hồi của API và cách xử lý một số lỗi thường gặp về địa chỉ đầu vào mà API phát hiện.

Lưu ý: Để hiểu rõ hơn về cách API xử lý các lỗi liên quan đến địa chỉ đầu vào, hãy Thử bản minh hoạ. Bản minh hoạ cho phép bạn nhập địa chỉ rồi xem phản hồi dưới dạng nội dung trực quan và dưới dạng đối tượng JSON.

Giới thiệu về nội dung phản hồi

Đối tượng JSON biểu thị phản hồi xác thực chứa hai thuộc tính cấp cao nhất: result thuộc loại ValidationResult và 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 mô tả cách diễn giải thuộc tính result. Để biết thêm thông tin về responseID, hãy xem phần Xác thực địa chỉ đã cập nhật và Gửi ý kiến phản hồi về việc xác thực địa chỉ.

Tìm hiểu thuộc tính kết quả

Thuộc tính verdict trong phản hồi xác thực cho biết kết quả tổng thể của quá trình xác thực. Thuộc tính verdict chứa các thuộc tính sau:

  • inputGranularity

    Cho biết mức độ chi tiết của địa chỉ đầu vào như được xác định bằng cách phân tích cú pháp địa chỉ nhưng không xác thực. Ví dụ: các thuộc tính này có thể chứa PREMISE cho địa chỉ phân giải thành kết quả cấp toà nhà, BLOCK cho địa chỉ phân giải thành một khối hoặc ROUTE cho địa chỉ chi tiết trên một tuyến đường (chẳng hạn như đường phố, đường hoặc đường cao tốc).

  • validationGranularity

    Cho biết mức độ chi tiết mà API có thể xác thực địa chỉ. Xin lưu ý rằng đây là độ chi tiết của địa chỉ đã xác thực chứ không phải độ chi tiết của địa chỉ được trả về trong address.formattedAddress hoặc address.postalAddress.

  • geocodeGranularity

    Cho biết mức độ chi tiết của vị trí mã địa lý được tạo.

  • addressComplete

    Đúng nếu API coi địa chỉ là hoàn chỉnh. Điều đó có nghĩa là không có mã thông báo chưa được phân giải (chuỗi địa chỉ hoặc ký hiệu), thành phần địa chỉ không mong muốn hoặc thành phần địa chỉ bị thiếu được liệt kê trong thuộc tính address.

  • hasUnconfirmedComponents, hasInferredComponents, hasReplacedComponents

    Các thuộc tính cho biết liệu có ít nhất một thành phần địa chỉ không thể được phân loại hoặc xác thực hay không, nếu có ít nhất một thành phần địa chỉ được suy ra (được thêm vào) không có trong dữ liệu nhập và liệu có ít nhất một thành phần địa chỉ được thay thế hay không.

Phán quyết cho địa chỉ đầy đủ với các thành phần được suy luận

Ví dụ sau đây thể hiện thuộc tính verdict cho một địa chỉ đầy đủ với các thành phần được suy luận:

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

Lưu ý rằng mức độ chi tiết sẽ phân giải thành một cơ sở và địa chỉ đó là đầy đủ, nhưng API suy ra giá trị của một số thành phần. Trong ví dụ này, địa chỉ nhập đã bỏ qua mã ZIP của Hoa Kỳ mà API có thể suy ra từ phần còn lại của địa chỉ. Hãy xem phần Thành phần của địa chỉ được suy luận để biết ví dụ đầy đủ hơn.

Phán quyết cho địa chỉ có các thành phần chưa được xác nhận

Mặc dù địa chỉ đầu vào có thể được coi là hoàn chỉnh ngay cả khi có thành phần được suy luận, nhưng địa chỉ không thể được coi là hoàn chỉnh nếu có bất kỳ mã thông báo địa chỉ nào chưa được giải quyết, thành phần địa chỉ không mong muốn hoặc thành phần địa chỉ bị thiếu.

Trong ví dụ tiếp theo, hasUnconfirmedComponents được đặt thành true để cho biết rằng địa chỉ có ít nhất một thành phần địa chỉ không thể phân loại hoặc xác thực được:

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

Trong trường hợp này, mức độ chi tiết của địa chỉ đã xác thực và mã hoá địa lý sẽ được đặt thành OTHER và thuộc tính addressComplete sẽ bị bỏ qua trong phản hồi để cho biết rằng địa chỉ chưa hoàn chỉnh. Hãy xem phần Thành phần địa chỉ còn thiếu và chưa được xác nhận để biết ví dụ đầy đủ hơn.

Câu trả lời mẫu

Các phần sau đây hiển thị câu trả lời cho nhiều trường hợp, bao gồm cả địa chỉ đầy đủ và các lỗi xác thực địa chỉ phổ biến. Trong các ví dụ sau:

  • Nếu phản hồi chứa addressComplete được đặt thành true, thì API đã xác định rằng địa chỉ đầu vào có chất lượng tốt.

  • Nếu API xác thực địa chỉ cho biết API đã thực hiện những thay đổi quan trọng đối với địa chỉ hoặc có lỗi trong địa chỉ, thì bạn cần xác nhận địa chỉ được trả về với khách hàng của mình.

Địa chỉ đầy đủ có chất lượng tốt

Khi xác định rằng địa chỉ đã hoàn chỉnh, API sẽ đặt addressComplete thành true trong thuộc tính verdict của phản hồi.

Ví dụ:

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

Thuộc tính address của phản hồi chứa tất cả thông tin chi tiết về địa chỉ do API xác định. Phản hồi bao gồm thuộc tính formattedAddress, chứa địa chỉ đã chỉnh sửa và xác thực dưới dạng một chuỗi một dòng. Bạn nên sử dụng địa chỉ một dòng có trong trường formattedAddress cho địa chỉ đầy đủ, vì địa chỉ này có thể chứa các nội dung sửa và bổ sung nhỏ, chẳng hạn như viết hoa và ZIP+4 ở Hoa Kỳ.

Thuộc tính address cũng cho biết liệu có bất kỳ vấn đề nào (do API xác định) đối với từng thành phần địa chỉ hay không. Đối với mỗi thành phần, chẳng hạn như tên đường phố hoặc thành phố, trường address sẽ chứa trường confirmationLevel. Các giá trị có thể bao gồm:

  • CONFIRMED cho biết API có thể xác minh rằng thành phần này tồn tại
  • UNCONFIRMED_BUT_PLAUSIBLE cho biết thành phần không thể được xác nhận nhưng điều này là hợp lý
  • UNCONFIRMED_AND_SUSPICIOUS cho biết thành phần này chưa được xác nhận và có thể không chính xác.

Ví dụ:

"address": {
  // Validated address as a single string.
  "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
  // Individual validated address components.
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043-1351",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  // Validation results for each component.
  "addressComponents": [
    {
      "componentName": {
        "text": "1600",
        "languageCode": "en"
      },
      "componentType": "street_number",
      "confirmationLevel": "CONFIRMED"
    },
    {
      "componentName": {
        "text": "Amphitheatre Pkwy",
        "languageCode": "en"
      },
      "componentType": "route",
      "confirmationLevel": "CONFIRMED"
    },
    …
  ]
  // List of any missing, unconfirmed, or unresolved address components.
  // These properties are omitted from the response if they are empty.
  "missingComponentTypes": [],
  "unconfirmedComponentTypes": [],
  "unresolvedTokens": []
}

Thành phần địa chỉ được suy luận

Nếu địa chỉ nhập không chứa địa chỉ đầy đủ, API sẽ cố gắng thêm mọi thành phần địa chỉ bị thiếu vào phản hồi. Các thành phần đã thêm này được gọi là thành phần địa chỉ được suy luận.

Ví dụ: bạn sử dụng địa chỉ nhập sau:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1600 Amphitheatre Pkwy"]
  }
}

Xin lưu ý rằng địa chỉ nhập này không chứa mã bưu chính của Hoa Kỳ. API có thể xác định mã ZIP từ phần còn lại của địa chỉ nhập và thêm mã đó vào phản hồi.

Trong ví dụ này, thuộc tính verdict đặt hasInferredComponents thành true để cho biết rằng API suy ra giá trị của một hoặc nhiều thành phần. Tuy nhiên, vì đây là một lần chỉnh sửa nhỏ nên API sẽ đặt addressComplete thành true để cho biết địa chỉ đầu vào vẫn có chất lượng tốt.

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

Đối với thành phần được dự đoán, API sẽ đặt inferred thành true trong phần tử tương ứng của mảng addressComponents của thuộc tính address:

{
  "componentName": {
    "text": "94043"
  },
  "componentType": "postal_code",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
}

Lỗi chính tả trong địa chỉ nhập

Lỗi chính tả trong địa chỉ nhập, chẳng hạn như lỗi chính tả trong thành phố hoặc tiểu bang, là phổ biến. Ví dụ: thay vì " Mountain View", bạn hãy nhập "MontainView" làm phần vị trí của địa chỉ:

{
  "address": {
    "regionCode" : "US",
    "locality" : "MontainView",
    "addressLines" : ["1600 Amphitheatre Pkwy"]
  }
}

Trong ví dụ này, thuộc tính verdict cho biết thuộc tính này suy ra giá trị của một hoặc nhiều thành phần, đồng thời đặt addressComplete thành true để cho biết địa chỉ đầu vào có chất lượng tốt vì vẫn có thể phân giải địa chỉ:

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

API cố gắng phân giải địa chỉ về đúng chính tả. Phần tử địa chỉ tương ứng trong mảng addressComponents của thuộc tính address hiển thị chuỗi đã sửa trong thuộc tính text, đồng thời cho biết rằng đã xảy ra lỗi chính tả bằng cách đặt spellCorrected thành true:

{
    "componentName": {
        "text": "Mountain View",
        "languageCode": "en"
    },
    "componentType": "locality",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

Thành phần địa chỉ bị thiếu và chưa được xác nhận

Người dùng có thể bỏ qua một phần của địa chỉ nhập. Trong ví dụ bên dưới, người dùng nhập số nhà nhưng không nhập tên đường phố:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600"]
  }
}

Trong trường hợp này, kết quả bỏ qua thuộc tính addressComplete vì thiếu quá nhiều thông tin để API có thể phân giải địa chỉ. API cũng đặt hasUnconfirmedComponents thành true để cho biết rằng địa chỉ này có các thành phần chưa được xác nhận:

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

Ngoài ra, xin lưu ý rằng validationGranularity và geocodeGranularity được đặt thành OTHER vì API không thể phân giải địa chỉ.

Trong mảng addressComponents của thuộc tính address, API sẽ đánh dấu thành phần số nhà là UNCONFIRMED_BUT_PLAUSIBLE:

{
  "componentName": {
    "text": "1600",
    "languageCode": "en"
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}

Và cuối cùng, API sẽ điền các thành phần bị thiếu trong dữ liệu đầu vào và những thành phần không thể xác nhận vào các mảng missingComponentTypes và unconfirmedComponentTypes của thuộc tính address:

"missingComponentTypes": [
  "route",
  "postal_code"
],
"unconfirmedComponentTypes": [
  "street_number"
]

Tìm hiểu các giá trị độ chi tiết

Các giá trị độ chi tiết trong phản hồi cung cấp thông tin chi tiết về mức độ thô hoặc mức độ chính xác của API trong việc diễn giải địa chỉ. Ví dụ: bạn sử dụng địa chỉ đầu vào sau:

{
  "address": {
    "regionCode": "US",
    "locality": "Northampton",
    "addressLines": ["6 South Main Street APT 456"]
  }
}

Trong ví dụ này, API tìm số nhà trong cơ sở dữ liệu USPS nhưng không thể tìm thấy số căn hộ. Ngoài ra, API không thể tìm thấy một mã địa lý chính xác cho số đường phố "6", nhưng có thể tìm thấy một mã cho "4" và "8". Trong trường hợp này, API sẽ trả về verdict sau:

"verdict": {
    "inputGranularity": "SUB_PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE_PROXIMITY",
    "addressComplete": true,
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

Nội dung phản hồi này:

  • inputGranularity là SUB_PREMISE vì API có thể phân tích cú pháp địa chỉ đầu vào ở cấp căn hộ. inputGranularity chỉ áp dụng cho các API có khả năng phân tích cú pháp địa chỉ nhập. Thao tác này không áp dụng cho hoạt động xác thực được thực hiện trên địa chỉ đó.

  • validationGranularity là PREMISE vì API có thể xác thực sự tồn tại của số đường phố "6" nhưng không phải là "APT 456". Mặc dù API không thể xác thực "APT 456", nhưng mã này vẫn có trong trường đầu ra formattedAddress và postalAddress.

  • geocodeGranularity là PREMISE_PROXIMITY vì API chỉ có thể nội suy vị trí mã địa lý, nên không thể tìm thấy mã địa lý cho địa chỉ đường phố được nhập chính xác.

Địa chỉ do USPS phát hiện thấy

Khi USPS xác định một địa chỉ được tạo giả tạo, trường errorMessage của thuộc tính uspsData của phản hồi sẽ chứa thông báo lỗi mô tả vấn đề. Ví dụ:

"uspsData": {
    "errorMessage": "AMS API processing was terminated due to the detection of
    what is determined to be an artificially created address. No address beyond
    this point has been validated and/or processed. If you believe this address
    was identified in error, please contact your Vendor."
}

Việc gửi các địa chỉ được tạo giả tạo tới API có thể dẫn đến việc mất quyền truy cập vào cơ sở dữ liệu USPS. Khi nhận được thông báo lỗi này, bạn nên điều tra nguồn của địa chỉ để ngăn việc gửi thêm nhiều địa chỉ giả tới API.

Biện pháp bảo mật này được thiết kế để ngăn chặn hành vi tạo danh sách địa chỉ bất thường bằng cách phát hiện thời điểm địa chỉ đã gửi có vẻ như đã được tạo một cách giả tạo và không được lấy một cách hợp pháp. Trường hợp này rất hiếm khi xảy ra.