Trang này được dịch bởi Cloud Translation API.

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 cho các ví dụ, nhưng phương pháp này tương tự như gRPC.

Sau khi xác thực một địa chỉ, bạn có thể tuỳ ý trả về cho Google thông tin về kết quả của việc 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 phản hồi 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

Chuyể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 có í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ạn bỏ qua, API này sẽ suy luận khu vực từ địa chỉ. Tuy nhiên, để đạt được hiệu suất tốt nhất, bạn nên đưa regionCode vào 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 chiều dài của trường address bị giới hạn ở 280 ký tự.

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

Bưu điện Hoa Kỳ (USPS®)¹ duy trì Hệ thống hỗ trợ độ chính xác lập trình (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 CASS, 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 bị thiếu của một địa chỉ, chuẩn hóa 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 đường phố và số nhà cùng với thành phố, tiểu bang và mã ZIP:

{
  "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ã hoá địa lý cho địa chỉ.

Lưu ý: Để biết thông tin về sự khác biệt giữa address và geocode, hãy xem bài viết Địa chỉ so với mã địa lý.
Trường verdict, thuộc loại Kết quả, chứa quy trình xác thực địa chỉ và kết quả mã hoá địa lý.
Trường metadata, thuộc loại AddressMetadata, chứa siêu dữ liệu cho địa chỉ.
Một 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 phần đị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ỉ. Ví dụ: người dùng có thể thay đổi hoặc chỉnh 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ỉ mà 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 tiếp theo tới API Xác thực địa chỉ.

Khi đư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 này.

Ví dụ: phản hồi ở 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ố đường phố từ 1600 thành 1500. Khi bạn xác thực lại địa chỉ, hãy bao gồm trường previousResponseId với giá trị của 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, tiếp tục truyền giá trị của responseId từ phản hồi đầu tiên trong trường previousResponseId trên 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 như một phần của 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 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 nội dung Lỗi.

Nền tảng Google Maps là một Bên được cấp phép không độc quyền của Dịch vụ bưu chính Hoa Kỳ. (Các) nhãn hiệu sau thuộc sở hữu của Bưu chính Hoa Kỳ và được sử dụng với sự cho phép: Bưu điện Hoa Kỳ, CASSTM, Chứng nhận CASSTM. ↩