Xác thực địa chỉ

Để xác thực địa chỉ bằng API Xác thực địa chỉ, hãy gọi phương thức validateAddress (REST) hoặc validateAddress (gRPC). Tài liệu này sử dụng REST để làm ví dụ, nhưng cách tiếp cận cũng tương tự như gRPC.

Sau khi xác thực một địa chỉ, bạn có thể tuỳ ý trả lại thông tin cho Google về kết quả xác thực địa chỉ bằng cách gọi phương thức provideValidationFeedback (REST) hoặc ProvideValidationFeedback (gRPC). Để biết thông tin và ví dụ, hãy xem phần Cung cấp ý kiến phản hồi về việc xác thực địa chỉ.

Yêu cầu xác thực địa chỉ

Xác thực địa chỉ bằng cách gửi yêu cầu POST đến phương thức validateAddress:

https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY

Truyền nội dung JSON vào yêu cầu xác định địa chỉ để xác thực:

curl -X POST -d '{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  }
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY"

Trường address trong phần nội dung yêu cầu, thuộc loại PostalAddress, phải chứa ít nhất một mục nhập trong addressLines.

• Trường regionCode là trường không bắt buộc. Nếu bỏ qua, API phỏng đoán vùng từ địa chỉ. Tuy nhiên, để đạt được hiệu suất tốt nhất, bạn nên đưa vào regionCode nếu bạn biết. Để biết danh sách các khu vực được hỗ trợ, hãy xem các khu vực được hỗ trợ.

• Tổng độ dài của trường address là 280 ký tự.

Bật CASSTM (không bắt buộc) khi xác thực địa chỉ

Hệ thống bưu chính Hoa Kỳ® (USPS®)¹ duy trì Hệ thống hỗ trợ độ chính xác mã hóa (CASSTM) để hỗ trợ và chứng nhận các nhà cung cấp dịch vụ xác thực địa chỉ. Dịch vụ được chứng nhận CASSTM, chẳng hạn như API xác thực địa chỉ, đã được xác nhận về khả năng điền thông tin còn thiếu của địa chỉ, chuẩn hóa địa chỉ và cập nhật địa chỉ để cung cấp cho bạn địa chỉ mới nhất và chính xác nhất.

Riêng đối với các khu vực "Hoa Kỳ" và "PR", bạn có thể tuỳ ý bật tính năng xử lý CASS bằng cách đặt enableUspsCass thành true trong nội dung yêu cầu.

Để có kết quả tốt nhất khi sử dụng CASS, hãy cung cấp địa chỉ bao gồm số nhà và đường phố cùng với thành phố, tiểu bang và mã bưu chính:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "administrativeArea": "CA",
    "postalCode": "94043",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  },
  "enableUspsCass": true
}

Bạn cũng có thể chỉ định địa chỉ đầy đủ dưới dạng hai chuỗi trong mảng addressLines:

{
  "address": {
    "regionCode": "US",
    "addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
  },
  "enableUspsCass": true
}

Phản hồi xác thực địa chỉ

Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái HTTP 200 OK và nội dung phản hồi chứa thông tin về địa chỉ đã xác thực.

Trường result của phản hồi chứa đối tượng ValidationResult. Đối tượng này bao gồm:

• Trường address, thuộc loại Address (Địa chỉ) chứa thông tin chi tiết về địa chỉ.

• Trường geocode, thuộc loại Mã địa lý, chứa thông tin mã địa lý cho địa chỉ.

• Trường verdict, thuộc loại Kết quả, chứa kết quả xác thực địa chỉ và mã hoá địa lý.

• Trường metadata, thuộc loại AddressMetadata, chứa siêu dữ liệu cho địa chỉ.

• Trường uspsData, thuộc loại USPSData, chứa dữ liệu USPS cho địa chỉ. Dữ liệu này chỉ có sẵn cho các địa chỉ ở Hoa Kỳ và Puerto Rico.

Vì phản hồi sau đây chứa addressComplete được đặt thành true, nên phản hồi cho biết địa chỉ này hoàn toàn hợp lệ, vì vậy, bạn không cần xác thực thêm. Nếu phản hồi cho biết một số phần của địa chỉ không hợp lệ, hãy nhắc người dùng kiểm tra và xác nhận mục nhập địa chỉ của họ.

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600",
            "languageCode": "en"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4223878,
        "longitude": -122.0841877
      },
      "plusCode": {
        "globalCode": "849VCWC8+X8"
      },
      "bounds": {
        "low": {
          "latitude": 37.4220699,
          "longitude": -122.084958
        },
        "high": {
          "latitude": 37.4226618,
          "longitude": -122.0829302
        }
      },
      "featureSizeMeters": 116.538734,
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g",
      "placeTypes": [
        "premise"
      ]
    },
    "metadata": {
      "business": false,
      "poBox": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRoute": "C909",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S"
    }
  },
  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

Xác thực địa chỉ đã cập nhật

Trong một số trường hợp, bạn có thể phải thực hiện nhiều lệnh gọi đến API xác thực địa chỉ cho một địa chỉ duy nhất. Ví dụ: người dùng có thể thay đổi hoặc sửa địa chỉ của họ sau khi xem kết quả của lần xác thực đầu tiên. Sau đó, bạn thực hiện lần xác thực thứ hai trên địa chỉ cập nhật.

Mỗi lệnh gọi API Xác thực địa chỉ sẽ trả về một giá trị duy nhất trong trường responseId của phản hồi. Nếu một địa chỉ bạn đang cố gắng xác thực cần được xác thực lại, hãy chuyển responseId từ phản hồi xác thực đầu tiên trong trường previousResponseId cho tất cả các yêu cầu theo dõi đến API xác thực địa chỉ.

Bằng cách đưa trường previousResponseId vào yêu cầu mới, bạn có thể giúp chúng tôi cải thiện độ chính xác tổng thể của API.

Ví dụ: phản hồi hiển thị ở trên bao gồm trường responseId:

  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"

Sau đó, bạn cần xác thực lại địa chỉ bằng cách thay đổi số nhà từ 1600 thành 1500. Khi bạn xác thực lại địa chỉ, hãy thêm trường previousResponseId với giá trị responseId từ phản hồi đầu tiên:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

Đối với yêu cầu sử dụng CASS:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
  "enableUspsCass": true

}

Kết quả của mỗi lệnh gọi tiếp theo sẽ trả về một giá trị mới trong trường responseId. Tuy nhiên, hãy tiếp tục chuyển giá trị của responseId từ phản hồi đầu tiên trong trường previousResponseId ở tất cả các lệnh gọi tiếp theo để cập nhật địa chỉ.

Xử lý lỗi

API xác thực địa chỉ trả về các thông báo lỗi trong phản hồi cho lệnh gọi phương thức. Ví dụ: nếu bạn bỏ qua khoá API trong yêu cầu, thì phương thức này sẽ trả về:

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "status": "PERMISSION_DENIED"
  }
}

Nếu bạn bỏ qua một tham số nội dung bắt buộc, chẳng hạn như addressLines, phương thức này sẽ trả về:

{
  "error": {
    "code": 400,
    "message": "Address lines missing from request.",
    "status": "INVALID_ARGUMENT"
  }
}

Để biết thêm thông tin về lỗi và cách xử lý lỗi, hãy xem phần Lỗi.