Method: validateAddress

Xác thực địa chỉ.

Yêu cầu HTTP

POST https://addressvalidation.googleapis.com/v1:validateAddress

URL sử dụng cú pháp Chuyển mã gRPC.

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "address": {
    object (PostalAddress)
  },
  "previousResponseId": string,
  "enableUspsCass": boolean,
  "languageOptions": {
    object (LanguageOptions)
  },
  "sessionToken": string
}
Trường
address

object (PostalAddress)

Bắt buộc. Địa chỉ đang được xác thực. Bạn nên gửi địa chỉ chưa định dạng qua addressLines.

Tổng độ dài của các trường trong dữ liệu đầu vào này không được vượt quá 280 ký tự.

Bạn có thể xem các khu vực được hỗ trợ tại đây.

Giá trị languageCode trong địa chỉ đầu vào được dành riêng để sử dụng sau này và sẽ bị bỏ qua vào hôm nay. Kết quả địa chỉ đã xác thực sẽ được điền dựa trên ngôn ngữ ưu tiên cho địa chỉ đã cho, do hệ thống xác định.

Address Validation API bỏ qua các giá trị trong recipients và organization. Mọi giá trị trong các trường đó sẽ bị loại bỏ và không được trả về. Vui lòng không đặt các giá trị này.
previousResponseId

string

Trường này phải trống đối với yêu cầu xác thực địa chỉ đầu tiên. Nếu cần thêm nhiều yêu cầu để xác thực đầy đủ một địa chỉ (ví dụ: nếu những thay đổi mà người dùng thực hiện sau lần xác thực ban đầu cần được xác thực lại), thì mỗi yêu cầu tiếp theo phải điền responseId vào trường này từ phản hồi đầu tiên trong trình tự xác thực.
enableUspsCass

boolean

Bật chế độ tương thích với USPS CASS. Điều này chỉ ảnh hưởng đến trường google.maps.addressvalidation.v1.ValidationResult.usps_data của google.maps.addressvalidation.v1.ValidationResult. Lưu ý: đối với những yêu cầu có hỗ trợ CASS của USPS cho địa chỉ ở Puerto Rico, bạn phải cung cấp google.type.PostalAddress.region_code của address thành "PR" hoặc google.type.PostalAddress.administrative_area của address phải được cung cấp là "Puerto Rico" (không phân biệt chữ hoa chữ thường) hoặc "PR".

Bạn nên sử dụng address được tạo thành phần hoặc chỉ định ít nhất hai google.type.PostalAddress.address_lines, trong đó dòng đầu tiên chứa số nhà và tên đường, còn dòng thứ hai chứa thành phố, tiểu bang và mã zip.
languageOptions

object (LanguageOptions)

Không bắt buộc. Bản dùng thử: Tính năng này đang ở giai đoạn Bản dùng thử (trước khi phát hành công khai). Các sản phẩm và tính năng trước giai đoạn phát hành rộng rãi có thể được hỗ trợ hạn chế, đồng thời có thể những thay đổi đối với những sản phẩm và tính năng trước giai đoạn phát hành rộng rãi có thể không tương thích với những phiên bản trước giai đoạn phát hành rộng rãi. Các sản phẩm trước giai đoạn phát hành rộng rãi tuân theo Điều khoản cụ thể về dịch vụ của Nền tảng Google Maps. Để biết thêm thông tin, hãy xem nội dung mô tả các giai đoạn ra mắt.

Bật API xác thực địa chỉ để đưa thêm thông tin vào phản hồi.
sessionToken

string

Không bắt buộc. Một chuỗi xác định một phiên Tự động hoàn thành cho mục đích thanh toán. Phải là một URL và tên tệp an toàn ở định dạng base64, có độ dài tối đa 36 ký tự ASCII. Nếu không, hệ thống sẽ trả về lỗi INVALID_ARGUMENT.

Phiên bắt đầu khi người dùng thực hiện một truy vấn Tự động hoàn thành và kết thúc khi họ chọn một địa điểm và thực hiện lệnh gọi đến Chi tiết địa điểm hoặc Xác minh địa chỉ. Mỗi phiên có thể có nhiều truy vấn Tự động hoàn thành, theo sau là một yêu cầu Chi tiết địa điểm hoặc Xác thực địa chỉ. Thông tin đăng nhập dùng cho mỗi yêu cầu trong một phiên phải thuộc cùng một dự án Google Cloud Console. Sau khi một phiên kết thúc, mã thông báo sẽ không còn hợp lệ nữa; ứng dụng của bạn phải tạo một mã thông báo mới cho mỗi phiên. Nếu bạn bỏ qua thông số sessionToken hoặc sử dụng lại mã thông báo phiên, thì phiên sẽ bị tính phí như thể không có mã thông báo phiên nào được cung cấp (mỗi yêu cầu được tính phí riêng).

Lưu ý: Bạn chỉ có thể sử dụng tính năng Xác thực địa chỉ trong các phiên có Autocomplete (New) API, chứ không phải Autocomplete API. Hãy truy cập vào https://developers.google.com/maps/documentation/places/web-service/session-pricing để biết thêm chi tiết.

Nội dung phản hồi

Nội dung phản hồi yêu cầu xác thực địa chỉ.

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "result": {
    object (ValidationResult)
  },
  "responseId": string
}
Trường
result

object (ValidationResult)

Kết quả xác thực địa chỉ.
responseId

string

UUID xác định phản hồi này. Nếu cần xác thực lại địa chỉ, thì mã nhận dạng duy nhất (UUID) này phải đi kèm với yêu cầu mới.

PostalAddress (Địa chỉ bưu điện)

Biểu thị địa chỉ bưu chính, ví dụ: địa chỉ giao hàng qua đường bưu chính hoặc địa chỉ thanh toán. Khi có địa chỉ bưu chính, dịch vụ bưu chính có thể giao hàng đến một cơ sở, hộp thư bưu chính hoặc địa chỉ tương tự. Lớp này không dùng để mô hình hoá các vị trí địa lý (đường, thị trấn, núi).

Trong trường hợp sử dụng thông thường, địa chỉ sẽ được tạo thông qua dữ liệu do người dùng nhập hoặc từ việc nhập dữ liệu hiện có, tuỳ thuộc vào loại quy trình.

Lời khuyên về việc nhập / chỉnh sửa địa chỉ: – Sử dụng tiện ích địa chỉ sẵn sàng quốc tế hoá, chẳng hạn như https://github.com/google/libaddressinput) – Không nên cung cấp cho người dùng các phần tử trên giao diện người dùng để nhập hoặc chỉnh sửa các trường ở bên ngoài quốc gia sử dụng trường đó.

Để biết thêm hướng dẫn về cách sử dụng giản đồ này, vui lòng xem: https://support.google.com/business/answer/6397478

Biểu diễn dưới dạng JSON 
{
  "revision": integer,
  "regionCode": string,
  "languageCode": string,
  "postalCode": string,
  "sortingCode": string,
  "administrativeArea": string,
  "locality": string,
  "sublocality": string,
  "addressLines": [
    string
  ],
  "recipients": [
    string
  ],
  "organization": string
}
Trường
revision

integer

Bản sửa đổi giản đồ của PostalAddress. Mọi giá trị khác 0 sẽ khiến API trả về lỗi INVALID_ARGUMENT.
regionCode

string

Không bắt buộc. Mã vùng CLDR của quốc gia/khu vực của địa chỉ. Hãy xem https://cldr.unicode.org/ và https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html để biết thông tin chi tiết. Ví dụ: "CH" cho Thuỵ Sĩ. Nếu bạn không cung cấp mã khu vực, hệ thống sẽ suy luận mã khu vực từ địa chỉ. Để đạt được hiệu suất cao nhất, bạn nên thêm mã khu vực nếu biết. Việc có các khu vực không nhất quán hoặc lặp lại có thể dẫn đến hiệu suất kém. Ví dụ: nếu addressLines đã bao gồm khu vực đó, thì bạn không nên cung cấp lại mã khu vực trong trường này. Bạn có thể xem các khu vực được hỗ trợ trong phần Câu hỏi thường gặp.
languageCode

string

Mã ngôn ngữ trong địa chỉ đầu vào được dành để sử dụng trong tương lai và hiện bị bỏ qua. API này trả về địa chỉ bằng ngôn ngữ thích hợp cho vị trí của địa chỉ.
postalCode

string

Không bắt buộc. Mã bưu chính của địa chỉ. Không phải quốc gia nào cũng sử dụng hoặc yêu cầu phải có mã bưu chính, nhưng ở Hoa Kỳ, các quốc gia này có thể kích hoạt quy trình xác thực bổ sung với các phần khác của địa chỉ (ví dụ: xác thực tiểu bang/mã bưu chính tại Hoa Kỳ).
sortingCode

string

Không bắt buộc. Mã sắp xếp bổ sung, dành riêng cho quốc gia. Mã này không được sử dụng ở hầu hết các khu vực. Khi giá trị được sử dụng, giá trị này có thể là một chuỗi như "CEDEX", theo sau là một số (ví dụ: "CEDEX 7") hoặc chỉ là một số, đại diện cho "mã ngành" (Jamaica), "chỉ báo khu vực giao hàng" (Malawi) hoặc "chỉ báo bưu điện" (ví dụ: Côte d'Côte d'iban).
administrativeArea

string

Không bắt buộc. Phân khu hành chính cao nhất dùng cho địa chỉ bưu chính của một quốc gia hoặc khu vực. Ví dụ: tiểu bang, tỉnh, oblast hoặc tỉnh. Cụ thể, đối với Tây Ban Nha, đây là tỉnh chứ không phải cộng đồng tự trị (ví dụ: "Barcelona" chứ không phải "Catalonia"). Nhiều quốc gia không sử dụng khu vực hành chính trong địa chỉ bưu chính. Ví dụ: ở Thuỵ Sĩ, bạn không nên điền giá trị này.
locality

string

Không bắt buộc. Thường đề cập đến phần thành phố/thị trấn của địa chỉ. Ví dụ: thành phố ở Hoa Kỳ, comune ở Ý, thị trấn bưu chính ở Vương quốc Anh. Ở những khu vực trên thế giới mà địa phương không được xác định rõ ràng hoặc không phù hợp với cấu trúc này, hãy để trống địa phương và sử dụng addressLines.
sublocality

string

Không bắt buộc. Khu vực phụ của địa chỉ. Ví dụ: khu dân cư, quận, huyện.
addressLines[]

string

Bắt buộc. Dòng địa chỉ phi cấu trúc mô tả các cấp thấp hơn của một địa chỉ.

Vì các giá trị trong addressLines không có thông tin về loại và đôi khi có thể chứa nhiều giá trị trong một trường (ví dụ: "Austin, TX"), nên bạn cần phải sắp xếp thứ tự dòng một cách rõ ràng. Thứ tự của các dòng địa chỉ phải là "thứ tự phong bì" đối với quốc gia/khu vực của địa chỉ.

Biểu diễn cấu trúc tối thiểu được phép của một địa chỉ bao gồm tất cả thông tin được đặt trong addressLines. Nếu bạn không cung cấp regionCode, thì khu vực sẽ được suy ra từ các dòng địa chỉ.

Bạn nên tạo một địa chỉ chỉ chứa addressLines, sau đó mã hoá địa lý để xử lý các địa chỉ hoàn toàn không có cấu trúc (thay vì đoán xem phần nào của địa chỉ là địa phương hoặc khu vực hành chính).
recipients[]

string

Vui lòng tránh đặt trường này. API Xác thực địa chỉ hiện không sử dụng thông tin này. Mặc dù tại thời điểm này, API sẽ không từ chối các yêu cầu có nhóm trường này, nhưng thông tin sẽ bị loại bỏ và không được trả về trong phản hồi.
organization

string

Vui lòng tránh đặt trường này. API Xác thực địa chỉ hiện không sử dụng thông tin này. Mặc dù tại thời điểm này, API sẽ không từ chối các yêu cầu có nhóm trường này, nhưng thông tin sẽ bị loại bỏ và không được trả về trong phản hồi.

LanguageOptions

Bản dùng thử: Tính năng này đang ở giai đoạn Bản dùng thử (trước khi phát hành công khai). Các sản phẩm và tính năng trước giai đoạn phát hành rộng rãi có thể được hỗ trợ hạn chế, đồng thời có thể những thay đổi đối với những sản phẩm và tính năng trước giai đoạn phát hành rộng rãi có thể không tương thích với những phiên bản trước giai đoạn phát hành rộng rãi. Các sản phẩm trước giai đoạn phát hành rộng rãi tuân theo Điều khoản cụ thể về dịch vụ của Nền tảng Google Maps. Để biết thêm thông tin, hãy xem nội dung mô tả về giai đoạn ra mắt.

Cho phép API Xác thực địa chỉ đưa thêm thông tin vào phản hồi.

Biểu diễn dưới dạng JSON 
{
  "returnEnglishLatinAddress": boolean
}
Trường
returnEnglishLatinAddress

boolean

Xem trước: Trả về google.maps.addressvalidation.v1.Address bằng tiếng Anh. Hãy xem google.maps.addressvalidation.v1.ValidationResult.english_latin_address để biết chi tiết.

ValidationResult

Kết quả xác thực địa chỉ.

Biểu diễn dưới dạng JSON 
{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  },
  "englishLatinAddress": {
    object (Address)
  }
}
Trường
verdict

object (Verdict)

Cờ cho kết quả tổng thể
address

object (Address)

Thông tin về chính địa chỉ đó, chứ không phải mã địa lý.
geocode

object (Geocode)

Thông tin về vị trí và địa điểm mà địa chỉ được mã hoá địa lý.
metadata

object (AddressMetadata)

Thông tin khác liên quan đến khả năng phân phối. Không đảm bảo metadata được điền đầy đủ cho mọi địa chỉ được gửi đến API Xác thực địa chỉ.
uspsData

object (UspsData)

Các cờ bổ sung về khả năng phân phối do USPS cung cấp. Chỉ được cung cấp trong vùng US và PR.
englishLatinAddress

object (Address)

Bản dùng thử: Tính năng này đang ở giai đoạn Bản dùng thử (trước khi phát hành công khai). Các sản phẩm và tính năng trước giai đoạn phát hành rộng rãi có thể được hỗ trợ hạn chế và các thay đổi đối với các sản phẩm và tính năng trước giai đoạn phát hành rộng rãi có thể không tương thích với các phiên bản trước giai đoạn phát hành rộng rãi khác. Sản phẩm trước giai đoạn phát hành rộng rãi chịu sự điều chỉnh của Điều khoản dịch vụ dành riêng cho nền tảng Google Maps. Để biết thêm thông tin, hãy xem nội dung mô tả các giai đoạn ra mắt.

Địa chỉ được dịch sang tiếng Anh.

Bạn không thể sử dụng lại địa chỉ đã dịch làm dữ liệu đầu vào API. Dịch vụ cung cấp các thông báo này để người dùng có thể sử dụng tiếng mẹ đẻ xác nhận hoặc từ chối xác thực địa chỉ được cung cấp ban đầu.

Nếu một phần của địa chỉ không có bản dịch tiếng Anh, thì dịch vụ sẽ trả về phần đó bằng ngôn ngữ thay thế sử dụng chữ viết Latinh. Hãy xem tại đây để biết nội dung giải thích về cách chọn ngôn ngữ thay thế. Nếu một phần của địa chỉ không có bất kỳ bản dịch hoặc bản chuyển tự nào trong ngôn ngữ sử dụng chữ Latinh, thì dịch vụ sẽ trả về phần đó bằng ngôn ngữ địa phương được liên kết với địa chỉ.

Bật đầu ra này bằng cách sử dụng cờ google.maps.addressvalidation.v1.LanguageOptions.return_english_latin_address.

Lưu ý: trường google.maps.addressvalidation.v1.Address.unconfirmed_component_types trong englishLatinAddress và trường google.maps.addressvalidation.v1.AddressComponent.confirmation_level trong englishLatinAddress.address_components không được điền sẵn.

Kết quả

Thông tin tổng quan về kết quả xác thực địa chỉ và mã địa lý.

Biểu diễn dưới dạng JSON 
{
  "inputGranularity": enum (Granularity),
  "validationGranularity": enum (Granularity),
  "geocodeGranularity": enum (Granularity),
  "addressComplete": boolean,
  "hasUnconfirmedComponents": boolean,
  "hasInferredComponents": boolean,
  "hasReplacedComponents": boolean
}
Trường
inputGranularity

enum (Granularity)

Mức độ chi tiết của địa chỉ đầu vào. Đây là kết quả của quá trình phân tích cú pháp địa chỉ đầu vào và không đưa ra tín hiệu xác thực nào. Đối với các tín hiệu xác thực, hãy tham khảo validationGranularity bên dưới.

Ví dụ: nếu địa chỉ đầu vào bao gồm một số căn hộ cụ thể, thì inputGranularity ở đây sẽ là SUB_PREMISE. Nếu chúng tôi không thể so khớp số căn hộ trong cơ sở dữ liệu hoặc số căn hộ không hợp lệ, thì validationGranularity có thể là PREMISE trở xuống.
validationGranularity

enum (Granularity)

Cấp độ chi tiết mà API có thể xác thực đầy đủ địa chỉ. Ví dụ: validationGranularity của PREMISE cho biết tất cả các thành phần địa chỉ ở cấp PREMISE trở lên có thể được xác thực.

Có thể tìm thấy kết quả xác thực thành phần theo từng địa chỉ trong google.maps.addressvalidation.v1.Address.address_components.
geocodeGranularity

enum (Granularity)

Thông tin về độ chi tiết của geocode. Bạn có thể hiểu đây là ý nghĩa ngữ nghĩa của độ chính xác hoặc độ thô của vị trí được mã hoá địa lý.

Đôi khi, giá trị này có thể khác với validationGranularity ở trên. Ví dụ: cơ sở dữ liệu của chúng tôi có thể ghi nhận sự tồn tại của một số căn hộ nhưng không có vị trí chính xác của căn hộ đó trong một khu phức hợp căn hộ lớn. Trong trường hợp đó, validationGranularity sẽ là SUB_PREMISE nhưng geocodeGranularity sẽ là PREMISE.
addressComplete

boolean

Địa chỉ được coi là hoàn chỉnh nếu không có mã thông báo chưa được phân giải, không có thành phần địa chỉ bất ngờ hoặc bị thiếu. Nếu bạn không đặt chính sách này, hãy cho biết giá trị là false. Hãy xem các trường missingComponentTypes, unresolvedTokens hoặc unexpected để biết thêm thông tin chi tiết.
hasUnconfirmedComponents

boolean

Không thể phân loại hoặc xác thực ít nhất một thành phần địa chỉ, hãy xem google.maps.addressvalidation.v1.Address.address_components để biết thông tin chi tiết.
hasInferredComponents

boolean

Ít nhất một thành phần địa chỉ đã được suy luận (thêm) không có trong dữ liệu đầu vào, hãy xem google.maps.addressvalidation.v1.Address.address_components để biết chi tiết.
hasReplacedComponents

boolean

Ít nhất một thành phần địa chỉ đã được thay thế, xem google.maps.addressvalidation.v1.Address.address_components để biết chi tiết.

Độ chi tiết

Các mức độ chi tiết mà địa chỉ hoặc mã địa lý có thể có. Khi được dùng để cho biết mức độ chi tiết của một địa chỉ, các giá trị này cho biết mức độ chi tiết mà địa chỉ xác định một đích gửi thư. Ví dụ: địa chỉ như "123 Main Street, Redwood City, CA, 94061" xác định PREMISE, trong khi địa chỉ như "Redwood City, CA, 94061" xác định LOCALITY. Tuy nhiên, nếu chúng tôi không tìm thấy mã địa lý cho "123 Main Street" ở Redwood City, thì mã địa lý được trả về có thể có độ chi tiết là LOCALITY mặc dù địa chỉ này có độ chi tiết cao hơn.

Enum
GRANULARITY_UNSPECIFIED Giá trị mặc định. Giá trị này chưa được sử dụng.
SUB_PREMISE Kết quả ở cấp dưới toà nhà, chẳng hạn như căn hộ.
PREMISE Kết quả ở cấp bản dựng.
PREMISE_PROXIMITY Mã địa lý gần đúng vị trí ở cấp toà nhà của địa chỉ.
BLOCK Địa chỉ hoặc mã địa lý cho biết một khu vực. Chỉ được sử dụng ở những khu vực có địa chỉ ở cấp khối, chẳng hạn như Nhật Bản.
ROUTE Mã địa lý hoặc địa chỉ chi tiết theo tuyến đường, chẳng hạn như đường phố, đường hoặc đường cao tốc.
OTHER Tất cả các mức độ chi tiết khác được gộp chung với nhau vì không thể phân phối.

Địa chỉ

Thông tin chi tiết về địa chỉ sau khi xử lý. Quá trình xử lý sau bao gồm việc sửa các phần bị sai chính tả của địa chỉ, thay thế các phần không chính xác và suy luận các phần bị thiếu.

Biểu diễn dưới dạng JSON 
{
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "addressComponents": [
    {
      object (AddressComponent)
    }
  ],
  "missingComponentTypes": [
    string
  ],
  "unconfirmedComponentTypes": [
    string
  ],
  "unresolvedTokens": [
    string
  ]
}
Trường
formattedAddress

string

Địa chỉ đã xử lý sau, được định dạng dưới dạng địa chỉ một dòng theo quy tắc định dạng địa chỉ của khu vực nơi địa chỉ đó nằm.

Lưu ý: định dạng của địa chỉ này có thể không khớp với định dạng của địa chỉ trong trường postalAddress. Ví dụ: postalAddress luôn biểu thị quốc gia dưới dạng regionCode gồm 2 chữ cái, chẳng hạn như "US" hoặc "NZ". Ngược lại, trường này sử dụng tên quốc gia ở dạng dài hơn, chẳng hạn như "Hoa Kỳ" hoặc "New Zealand".
postalAddress

object (PostalAddress)

Địa chỉ sau xử lý được thể hiện dưới dạng địa chỉ bưu điện.
addressComponents[]

object (AddressComponent)

Danh sách không theo thứ tự. Các thành phần địa chỉ riêng lẻ của địa chỉ đã được định dạng và sửa, cùng với thông tin xác thực. Dữ liệu này cung cấp thông tin về trạng thái xác thực của từng thành phần.

Các thành phần địa chỉ không được sắp xếp theo một cách cụ thể. Đừng đưa ra bất kỳ giả định nào về thứ tự của các thành phần địa chỉ trong danh sách.
missingComponentTypes[]

string

Các loại thành phần dự kiến sẽ có trong địa chỉ gửi thư có định dạng chính xác nhưng không tìm thấy trong dữ liệu đầu vào VÀ không thể suy luận được. Các thành phần thuộc loại này không có trong formattedAddress, postalAddress hoặc addressComponents. Ví dụ: ['street_number', 'route'] cho dữ liệu nhập như "Boulder, Colorado, 80301, USA". Bạn có thể xem danh sách các loại tài sản có thể sử dụng tại đây.
unconfirmedComponentTypes[]

string

Các loại thành phần có trong addressComponents nhưng không xác nhận được là chính xác. Trường này được cung cấp để thuận tiện: nội dung của trường tương đương với việc lặp lại thông qua addressComponents để tìm kiểu của tất cả thành phần trong đó confirmationLevel không phải là CONFIRMED hoặc cờ inferred không được đặt thành true. Bạn có thể xem danh sách các loại có thể sử dụng tại đây.
unresolvedTokens[]

string

Mọi mã thông báo trong dữ liệu nhập không phân giải được. Đây có thể là dữ liệu đầu vào không được nhận dạng là một phần hợp lệ của địa chỉ. Ví dụ: đối với dữ liệu đầu vào như "Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US", các mã thông báo chưa phân giải có thể có dạng ["Parcel", "0000123123", "&", "0000456456"].

AddressComponent

Biểu thị một thành phần địa chỉ, chẳng hạn như đường phố, thành phố hoặc tiểu bang.

Biểu diễn dưới dạng JSON 
{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}
Trường
componentName

object (ComponentName)

Tên của thành phần này.
componentType

string

Loại của thành phần địa chỉ. Xem Bảng 2: Các loại bổ sung được dịch vụ Địa điểm trả về để biết danh sách các loại có thể có.
confirmationLevel

enum (ConfirmationLevel)

Cho biết mức độ chắc chắn rằng thành phần đó là chính xác.
inferred

boolean

Cho biết thành phần này không phải là một phần của dữ liệu đầu vào, nhưng chúng tôi đã suy luận thành phần này cho vị trí địa chỉ và cho rằng bạn nên cung cấp thành phần này để có địa chỉ đầy đủ.
spellCorrected

boolean

Cho biết nội dung sửa lỗi chính tả trong tên thành phần. API không phải lúc nào cũng gắn cờ các thay đổi từ một biến thể chính tả sang biến thể khác, chẳng hạn như khi thay đổi "centre" thành "center". Công cụ này cũng không phải lúc nào cũng gắn cờ lỗi chính tả phổ biến, chẳng hạn như khi thay đổi "Amphitheater Pkwy" thành "Amphitheater Pkwy".
replaced

boolean

Cho biết tên của thành phần đã được thay thế bằng một tên hoàn toàn khác, ví dụ: mã bưu chính không chính xác được thay thế bằng mã bưu chính chính xác cho địa chỉ. Đây không phải là thay đổi về mặt hình thức, thành phần đầu vào đã được thay đổi thành một thành phần khác.
unexpected

boolean

Cho biết một thành phần địa chỉ không được xuất hiện trong địa chỉ bưu chính của khu vực nhất định. Chúng tôi chỉ giữ lại giá trị này vì nó là một phần của dữ liệu đầu vào.

ComponentName

Trình bao bọc cho tên của thành phần.

Biểu diễn dưới dạng JSON 
{
  "text": string,
  "languageCode": string
}
Trường
text

string

Văn bản tên. Ví dụ: "5th Avenue" đối với tên đường hoặc "1253" đối với số nhà.
languageCode

string

Mã ngôn ngữ BCP-47. Điều này sẽ không xuất hiện nếu tên thành phần không được liên kết với một ngôn ngữ, chẳng hạn như số nhà.

ConfirmationLevel

Các giá trị có thể có cho cấp độ xác nhận.

Enum
CONFIRMATION_LEVEL_UNSPECIFIED Giá trị mặc định. Giá trị này không được sử dụng.
CONFIRMED Chúng tôi đã xác minh được rằng thành phần này tồn tại và có ý nghĩa trong bối cảnh của phần còn lại của địa chỉ.
UNCONFIRMED_BUT_PLAUSIBLE Không thể xác nhận thành phần này, nhưng có thể thành phần này tồn tại. Ví dụ: số nhà nằm trong một dải số hợp lệ đã biết trên một con đường mà không xác định được số nhà cụ thể.
UNCONFIRMED_AND_SUSPICIOUS Thành phần này chưa được xác nhận và có thể không chính xác. Ví dụ: một khu vực không phù hợp với phần còn lại của địa chỉ.

Mã địa lý

Chứa thông tin về địa điểm mà dữ liệu đầu vào được mã hoá địa lý.

Biểu diễn dưới dạng JSON 
{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}
Trường
location

object (LatLng)

Vị trí được mã hoá địa lý của dữ liệu đầu vào.

Bạn nên sử dụng mã địa điểm thay vì địa chỉ, toạ độ vĩ độ/kinh độ hoặc mã cộng. Việc sử dụng toạ độ khi định tuyến hoặc tính toán đường đi luôn dẫn đến việc điểm được chụp nhanh đến đường gần nhất với các toạ độ đó. Đây có thể không phải là con đường dẫn đến đích nhanh chóng hoặc an toàn và có thể không gần điểm truy cập vào cơ sở lưu trú. Ngoài ra, khi một vị trí được mã hoá địa lý đảo ngược, chúng tôi không thể đảm bảo rằng địa chỉ được trả lại sẽ khớp với địa chỉ ban đầu.
plusCode

object (PlusCode)

Plus code tương ứng với location.
bounds

object (Viewport)

Ranh giới của địa điểm được mã hoá địa lý.
featureSizeMeters

number

Kích thước của địa điểm được mã hoá địa lý, tính bằng mét. Đây là một chỉ số khác về độ thô của vị trí được mã hoá địa lý, nhưng ở kích thước thực tế thay vì ý nghĩa ngữ nghĩa.
placeId

string

Mã địa điểm của địa điểm mà thông tin đầu vào này mã hoá địa lý.

Để biết thêm thông tin về Mã địa điểm, hãy xem tại đây.
placeTypes[]

string

(Các) loại địa điểm mà dữ liệu đầu vào được mã hoá địa lý. Ví dụ: ['locality', 'political']. Bạn có thể xem danh sách đầy đủ các loại tại đây.

LatLng

Đối tượng đại diện cho cặp vĩ độ/kinh độ. Giá trị này được biểu thị dưới dạng cặp số đại diện cho vĩ độ và độ kinh độ. Trừ phi có quy định khác, đối tượng này phải tuân thủ tiêu chuẩn WGS84. Giá trị phải nằm trong phạm vi chuẩn hoá.

Biểu diễn dưới dạng JSON 
{
  "latitude": number,
  "longitude": number
}
Trường
latitude

number

Vĩ độ tính bằng độ. Giá trị này phải nằm trong khoảng [-90.0, +90.0].
longitude

number

Kinh độ tính bằng độ. Giá trị này phải nằm trong khoảng [-180.0, +180.0].

PlusCode

Mã cộng (http://plus.codes) là tham chiếu vị trí với hai định dạng: mã toàn cục xác định hình chữ nhật nhỏ hơn hoặc 14mx14m (1/8000 độ) và mã phức hợp, thay thế tiền tố bằng vị trí tham chiếu.

Biểu diễn dưới dạng JSON 
{
  "globalCode": string,
  "compoundCode": string
}
Trường
globalCode

string

Mã toàn cầu (đầy đủ) của địa điểm, chẳng hạn như "9FWM33GV+HQ", đại diện cho khu vực có diện tích 1/8000 độ x 1/8000 độ (~14 x 14 mét).
compoundCode

string

Mã hợp chất của địa điểm, chẳng hạn như "33GV+HQ, Ramberg, Na Uy", chứa hậu tố của mã chung và thay thế tiền tố bằng tên được định dạng của một thực thể tham chiếu.

Khung nhìn

Chế độ xem vĩ độ-kinh độ, được biểu thị dưới dạng hai điểm low và high đối diện nhau theo đường chéo. Khung nhìn được coi là một vùng kín, tức là bao gồm cả ranh giới. Giới hạn vĩ độ phải nằm trong khoảng từ -90 đến 90 độ và giới hạn kinh độ phải nằm trong khoảng từ -180 đến 180 độ. Có nhiều trường hợp như sau:

  • Nếu low = high, khung nhìn sẽ bao gồm một điểm duy nhất đó.

  • Nếu low.longitude > high.longitude, thì phạm vi kinh độ sẽ bị đảo ngược (khung nhìn vượt qua đường kinh độ 180 độ).

  • Nếu low.longitude = -180 độ và high.longitude = 180 độ, thì khung nhìn sẽ bao gồm tất cả kinh độ.

  • Nếu low.longitude = 180 độ và high.longitude = -180 độ, thì phạm vi kinh độ trống.

  • Nếu low.latitude > high.latitude, phạm vi vĩ độ sẽ trống.

Cả low và high đều phải được điền và không được để trống ô được thể hiện (như được chỉ định trong các định nghĩa ở trên). Chế độ xem trống sẽ dẫn đến lỗi.

Ví dụ: khung nhìn này bao gồm toàn bộ Thành phố New York:

{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }

Biểu diễn dưới dạng JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Trường
low

object (LatLng)

Bắt buộc. Điểm thấp của khung nhìn.
high

object (LatLng)

Bắt buộc. Điểm cao của khung nhìn.

AddressMetadata

Siêu dữ liệu về địa chỉ. Không đảm bảo metadata được điền đầy đủ cho mọi địa chỉ được gửi đến API Xác thực địa chỉ.

Biểu diễn dưới dạng JSON 
{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}
Trường
business

boolean

Cho biết đây là địa chỉ của một doanh nghiệp. Nếu không được đặt, hãy cho biết giá trị không xác định.
poBox

boolean

Cho biết địa chỉ của hộp thư bưu điện. Nếu không được đặt, hãy cho biết giá trị không xác định.
residential

boolean

Cho biết rằng đây là địa chỉ của một nơi cư trú. Nếu không được đặt, hãy cho biết giá trị không xác định.

UspsData

Dữ liệu của USPS cho địa chỉ. Không đảm bảo uspsData được điền đầy đủ cho mọi địa chỉ ở Hoa Kỳ hoặc Puerto Rico được gửi đến Address Validation API. Bạn nên tích hợp các trường địa chỉ dự phòng trong phản hồi nếu sử dụng uspsData làm phần chính của phản hồi.

Biểu diễn dưới dạng JSON 
{
  "standardizedAddress": {
    object (UspsAddress)
  },
  "deliveryPointCode": string,
  "deliveryPointCheckDigit": string,
  "dpvConfirmation": string,
  "dpvFootnote": string,
  "dpvCmra": string,
  "dpvVacant": string,
  "dpvNoStat": string,
  "dpvNoStatReasonCode": integer,
  "dpvDrop": string,
  "dpvThrowback": string,
  "dpvNonDeliveryDays": string,
  "dpvNonDeliveryDaysValues": integer,
  "dpvNoSecureLocation": string,
  "dpvPbsa": string,
  "dpvDoorNotAccessible": string,
  "dpvEnhancedDeliveryCode": string,
  "carrierRoute": string,
  "carrierRouteIndicator": string,
  "ewsNoMatch": boolean,
  "postOfficeCity": string,
  "postOfficeState": string,
  "abbreviatedCity": string,
  "fipsCountyCode": string,
  "county": string,
  "elotNumber": string,
  "elotFlag": string,
  "lacsLinkReturnCode": string,
  "lacsLinkIndicator": string,
  "poBoxOnlyPostalCode": boolean,
  "suitelinkFootnote": string,
  "pmbDesignator": string,
  "pmbNumber": string,
  "addressRecordType": string,
  "defaultAddress": boolean,
  "errorMessage": string,
  "cassProcessed": boolean
}
Trường
standardizedAddress

object (UspsAddress)

Địa chỉ được tiêu chuẩn hoá của USPS.
deliveryPointCode

string

Mã điểm giao hàng gồm 2 chữ số
deliveryPointCheckDigit

string

Số kiểm tra điểm giao hàng. Số này được thêm vào cuối mã vạch điểm giao hàng cho thư được quét bằng máy. Thêm tất cả các chữ số của delivery_point_barcode, deliveryPointCheckDigit, mã bưu chính và ZIP+4 lại với nhau sẽ được số chia hết cho 10.
dpvConfirmation

string

Các giá trị có thể có để xác nhận DPV. Trả về một ký tự hoặc không trả về giá trị nào.

  • N: Không xác nhận được thông tin số điện thoại chính và bất kỳ số điện thoại phụ nào qua DPV.
  • D: Địa chỉ chỉ được DPV xác nhận cho số chính và thiếu thông tin về số phụ.
  • S: Địa chỉ chỉ được xác nhận là DPV cho số chính và thông tin về số phụ có nhưng chưa được xác nhận.
  • Y: Địa chỉ đã được DPV xác nhận cho số chính và mọi số phụ.
  • Trống: Nếu phản hồi không chứa giá trị dpvConfirmation, thì tức là địa chỉ đó chưa được gửi để xác nhận DPV.
dpvFootnote

string

Chú thích trong quá trình xác thực điểm giao hàng. Bạn có thể nối nhiều chú thích cuối cùng với nhau trong cùng một chuỗi.

  • AA: Địa chỉ nhập khớp với tệp ZIP+4
  • A1: Địa chỉ nhập không khớp với tệp ZIP+4
  • BB: Đã khớp với DPV (tất cả thành phần)
  • CC: Số điện thoại phụ không khớp và không bắt buộc
  • C1: Số điện thoại phụ không khớp nhưng bắt buộc phải có
  • N1: Địa chỉ toà nhà cao tầng thiếu số phụ
  • M1: Thiếu số điện thoại chính
  • M3: Số điện thoại chính không hợp lệ
  • P1: Thiếu số hộp thư bưu điện, RR hoặc HC của địa chỉ nhập
  • P3: Số hộp thư bưu điện PO, RR hoặc HC không hợp lệ
  • F1: Địa chỉ nhập khớp với địa chỉ quân sự
  • G1: Địa chỉ nhập khớp với địa chỉ giao hàng chung
  • U1: Địa chỉ nhập khớp với một mã bưu chính duy nhất
  • PB: Địa chỉ đầu vào khớp với bản ghi PBSA
  • RR: Địa chỉ đã xác nhận DPV với thông tin PMB
  • R1: Địa chỉ đã xác nhận của DPV không có thông tin PMB
  • R7: Bản ghi Tuyến đường của hãng vận tải R777 hoặc R779
  • IA: Đã xác định địa chỉ được thông báo
  • TA: Số chính được so khớp bằng cách bỏ alpha ở cuối
dpvCmra

string

Cho biết địa chỉ có phải là CMRA (Cơ quan tiếp nhận thư thương mại) hay không – một doanh nghiệp tư nhân nhận thư cho khách hàng. Trả về một ký tự đơn.

  • Y: Địa chỉ là CMRA
  • N: Địa chỉ không phải là CMRA
dpvVacant

string

Địa điểm này có trống không? Trả về một ký tự.

  • Y: Địa chỉ trống
  • N: Địa chỉ không trống
dpvNoStat

string

Đây là địa chỉ không có số liệu thống kê hay địa chỉ đang hoạt động? Địa chỉ không có số liệu thống kê là những địa chỉ không liên tục có người ở hoặc địa chỉ mà USPS không cung cấp dịch vụ. Trả về một ký tự.

  • Y: Địa chỉ không hoạt động
  • N: Địa chỉ đang hoạt động
dpvNoStatReasonCode

integer

Cho biết loại NoStat. Trả về mã lý do dưới dạng int.

  • 1: IDA (Địa chỉ nhận thư nội bộ) – Địa chỉ không nhận thư trực tiếp từ USPS mà được gửi đến một địa chỉ nhận thư để phục vụ địa chỉ đó.
  • 2: CDS – Địa chỉ chưa thể giao hàng. Ví dụ: một phân mục mới đã xác định số lô và số chính nhưng chưa có cấu trúc nào về số người lưu trú.
  • 3: Va chạm – Các địa chỉ không thực sự xác nhận DPV.
  • 4: CMZ (Cao đẳng, Quân đội và các loại khác) – Mã bưu chính + 4 bản ghi mà USPS đã đưa vào dữ liệu.
  • 5: Thông thường – Cho biết những địa chỉ không nhận được hàng và không được tính là địa chỉ có thể giao hàng.
  • 6: Bắt buộc phải có thông tin phụ – Địa chỉ cần có thông tin phụ.
dpvDrop

string

Cờ cho biết thư được gửi đến một hộp thư duy nhất tại một trang web. Trả về một ký tự.

  • Y: Thư được phân phối đến một hộp thư duy nhất tại một trang web.
  • N: Thư không được phân phối đến một hộp thư duy nhất tại một trang web.
dpvThrowback

string

Cho biết thư không được gửi đến địa chỉ đường phố. Trả về một ký tự.

  • Y: Thư không được giao đến địa chỉ đường phố.
  • N: Thư được gửi đến địa chỉ đường phố.
dpvNonDeliveryDays

string

Cờ cho biết việc phân phối thư không được thực hiện vào tất cả các ngày trong tuần. Trả về một ký tự.

  • Y: Việc gửi thư không được thực hiện tất cả các ngày trong tuần.
  • N: Không có dấu hiệu nào cho thấy việc phân phối thư không được thực hiện hằng ngày trong tuần.
dpvNonDeliveryDaysValues

integer

Số nguyên xác định những ngày không phân phối. Bạn có thể truy vấn thông tin này bằng cờ bit: 0x40 – Chủ Nhật là ngày không giao hàng 0x20 – Thứ Hai là ngày không giao hàng 0x10 – Thứ Ba là ngày không giao hàng 0x08 – Thứ Tư là ngày không giao hàng 0x04 – Thứ Năm là ngày không giao hàng 0x02 – Thứ Sáu là ngày không giao hàng 0x01 – Thứ Bảy là ngày không giao hàng
dpvNoSecureLocation

string

Cờ cho biết có thể mở cửa, nhưng gói hàng sẽ không được để lại do lo ngại về an ninh. Trả về một ký tự.

  • Y: Gói sẽ không được giữ lại do lo ngại về bảo mật.
  • N: Không có dấu hiệu nào cho thấy gói sẽ không được giữ lại do lo ngại về bảo mật.
dpvPbsa

string

Cho biết địa chỉ đã được so khớp với bản ghi PBSA. Trả về một ký tự.

  • Y: Địa chỉ đã khớp với bản ghi PBSA.
  • N: Địa chỉ không khớp với bản ghi PBSA.
dpvDoorNotAccessible

string

Cờ cho biết những địa chỉ mà USPS không thể gõ cửa để giao thư. Trả về một ký tự.

  • Y: Không thể mở cửa.
  • N: Không có dấu hiệu cho thấy không thể tiếp cận cửa.
dpvEnhancedDeliveryCode

string

Cho biết rằng có nhiều mã trả về DPV hợp lệ cho địa chỉ. Trả về một ký tự.

  • Y: Địa chỉ đã được DPV xác nhận cho số chính và mọi số phụ.
  • N: Không xác nhận được thông tin số điện thoại chính và bất kỳ số điện thoại phụ nào qua DPV.
  • S: Địa chỉ đã được xác nhận bằng DPV chỉ cho số chính và thông tin số phụ có nhưng chưa được xác nhận, hoặc một chữ cái ở cuối số chính đã bị loại bỏ để so khớp DPV và cần có thông tin phụ.
  • D: Địa chỉ đã được xác nhận DPV cho số điện thoại chính và thiếu thông tin về số điện thoại phụ.
  • R: Địa chỉ đã được xác nhận nhưng được chỉ định cho tuyến đường ảo R777 và R779 và không cung cấp dịch vụ giao hàng qua USPS.
carrierRoute

string

Mã tuyến đường của hãng vận chuyển. Mã bốn ký tự bao gồm một tiền tố là một chữ cái và một mã chỉ định tuyến đường gồm ba chữ số.

Tiền tố:

  • C: Tuyến của hãng vận tải (hoặc tuyến trong thành phố)
  • R: Tuyến đường nông thôn
  • H: Tuyến đường theo hợp đồng đường cao tốc
  • B: Phần Hộp thư bưu điện
  • G: Đơn vị phân phối chung
carrierRouteIndicator

string

Chỉ báo sắp xếp tốc độ lộ trình của hãng vận chuyển.
ewsNoMatch

boolean

Địa chỉ giao hàng có thể so khớp, nhưng tệp EWS cho biết rằng địa chỉ giao hàng chính xác sẽ sớm có.
postOfficeCity

string

Thành phố có bưu điện chính.
postOfficeState

string

Trạng thái của bưu điện chính.
abbreviatedCity

string

Thành phố viết tắt.
fipsCountyCode

string

Mã hạt theo FIPS.
county

string

Tên hạt.
elotNumber

string

Số đường bay nâng cao (eLOT).
elotFlag

string

Cờ tăng dần/giảm dần eLOT (A/D).
poBoxOnlyPostalCode

boolean

Mã bưu chính chỉ dành cho hộp thư bưu chính.
pmbDesignator

string

Chỉ định đơn vị PMB (Private Mail Box – Hộp thư riêng).
pmbNumber

string

số PMB (Hộp thư cá nhân);
addressRecordType

string

Loại bản ghi địa chỉ khớp với địa chỉ đầu vào.

  • F: FIRM. Đây là kết quả trùng khớp với một Bản ghi doanh nghiệp. Đây là mức độ trùng khớp cao nhất có thể đối với một địa chỉ.
  • G: GIAO HÀNG CHUNG. Dữ liệu này khớp với một Hồ sơ phân phối chung.
  • H: TOÀ NHÀ / CHUNG CƯ. Đây là kết quả trùng khớp với bản ghi Toà nhà hoặc Căn hộ.
  • P: HỘP SAU KHI ĐĂNG KÝ. Đây là kết quả khớp với Hộp thư bưu điện.
  • R: HỢP ĐỒNG NỀN TẢNG hoặc KHU VỰC CẤP ĐƯỜNG: Đây là trường hợp trùng khớp với Hồ sơ Tuyến đường nông thôn hoặc hồ sơ Hợp đồng Đường cao tốc, cả hai hồ sơ này có thể có phạm vi Số hộp tương ứng.
  • S: BẢN GHI PHỐ: Đây là kết quả trùng khớp với một bản ghi đường phố có chứa một dải số chính hợp lệ.
defaultAddress

boolean

Chỉ báo cho biết đã tìm thấy địa chỉ mặc định, nhưng có các địa chỉ cụ thể hơn.
errorMessage

string

Thông báo lỗi khi truy xuất dữ liệu USPS. Trường này được điền khi USPS tạm ngưng xử lý do phát hiện địa chỉ được tạo một cách giả tạo.

Các trường dữ liệu USPS có thể không được điền khi xảy ra lỗi này.
cassProcessed

boolean

Chỉ báo cho biết yêu cầu đã được CASS xử lý.

UspsAddress

Hình minh hoạ địa chỉ ở Hoa Kỳ theo USPS.

Biểu diễn dưới dạng JSON 
{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}
Trường
firstAddressLine

string

Dòng địa chỉ đầu tiên.
firm

string

Tên công ty.
secondAddressLine

string

Dòng địa chỉ thứ hai.
urbanization

string

Tên đô thị hoá ở Puerto Rico.
cityStateZipAddressLine

string

Thành phố + tiểu bang + mã bưu chính.
city

string

Tên thành phố.
state

string

Mã tiểu bang gồm 2 chữ cái.
zipCode

string

Mã bưu chính, ví dụ: 10009.
zipCodeExtension

string

Phần mở rộng mã bưu chính gồm 4 chữ số, ví dụ: 5023.