Method: validateAddress

Xác thực một đị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. Địa chỉ chưa được định dạng phải được gửi qua addressLines.

Các trường trong dữ liệu đầu vào này không được dài 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ỉ cụ thể do hệ thống xác định.

API xác thực địa chỉ sẽ 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 chúng.
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. Việc 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ó bật CASS USPS cho địa chỉ ở Puerto Rico, bạn phải cung cấp google.type.PostalAddress.region_code của address dưới dạng "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ó 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ố và tên nhà, còn dòng thứ hai chứa thành phố, tiểu bang và mã bưu chính.
languageOptions

object (LanguageOptions)

Không bắt buộc. Bản xem trước: Tính năng này đang ở giai đoạn thử nghiệm (trước giai đoạn phát hành rộng rã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ể đượ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. Sản phẩm trước giai đoạn phát hành rộng rãi phải tuân thủ Đ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.

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à chuỗi base64 an toàn cho URL và tên tệp với độ dài tối đa 36 ký tự ASCII. Nếu không, lỗi INVALID_ARGUMENT sẽ được trả về.

Phiên hoạt động này bắt đầu khi người dùng tìm kiếm bằng tính năng 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 phần Thông tin chi tiết về địa điểm hoặc Xác thực địa chỉ. Mỗi phiên hoạt động có thể có nhiều truy vấn Tự động hoàn thành, theo sau là một yêu cầu Thông tin chi tiết về đị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 phiên kết thúc, mã thông báo không còn hợp lệ; ứng dụng của bạn phải tạo mã thông báo mới cho mỗi phiên. Nếu thông số sessionToken bị bỏ qua hoặc nếu bạn sử dụng lại mã thông báo phiên, thì phiên sẽ được 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 sẽ đượ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ó API Tự động hoàn thành (Mới), chứ không dùng được API Tự động hoàn thành. Hãy tham khả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

Phản hồi cho 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

Mã nhận dạng duy nhất (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)

Đại diện cho địa chỉ bưu chính, ví dụ: cho địa chỉ giao hàng qua bưu điện 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 trụ sở là P.O. Hộp hoặc thứ tự tương tự. Tính năng này không nhằm lập mô hình vị trí địa lý (đường, thị trấn, núi).

Trong cách sử dụng thông thường, một địa chỉ sẽ được tạo thông qua hoạt động đầu vào của người dùng 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. Bất kỳ giá trị nào 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 trong địa chỉ. Hãy tham khảo 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ã vùng thì mã đó sẽ được suy ra từ địa chỉ đó. Để đạt được hiệu suất tốt nhất, bạn nên thêm mã vùng 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ỉ nhập được dành riêng để sử dụng sau này và sẽ bị bỏ qua hôm nay. API 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 mã bưu chính phải xuất hiện, nhưng ở Hoa Kỳ, các quốc gia đó 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ã phân loại bổ sung, theo quốc gia cụ thể. Thông tin 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ị phải là một chuỗi như "CEDEX", có thể theo sau là một số (ví dụ: "CEDEX 7") hoặc chỉ một số, đại diện cho "mã lĩnh vực" (Jamaica), "chỉ báo khu vực giao hàng" (Malawi) hoặc "chỉ báo tại bưu điện" (ví dụ: Bờ Biển Ngà).
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ụ: bạn có thể nhập một tiểu bang, một tỉnh, một vùng hoặc một tỉnh. Cụ thể, đối với Tây Ban Nha, đây là tỉnh và không phải là 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 điện. Ví dụ: ở Thuỵ Sĩ thì không nên điền giá trị này.
locality

string

Không bắt buộc. Nói chung là phần thành phố/thị trấn của địa chỉ. Ví dụ: Thành phố ở Hoa Kỳ, xã CNTT, thị trấn có bưu điện của Vương quốc Anh. Trong các khu vực trên thế giới nơi các địa phương không được xác định rõ 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. Quận/phường của địa chỉ. Ví dụ: đây có thể là vùng lân cận, thị xã, quậ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ề kiểu 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 đảm bảo thứ tự dòng rõ ràng. Thứ tự của các dòng địa chỉ phải là "thứ tự phong bì" cho quốc gia/khu vực trong địa chỉ.

Cách trình bày 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, khu vực sẽ được suy ra từ các dòng địa chỉ.

Tạo một địa chỉ chỉ chứa addressLines, và sau đó mã hóa địa lý là cách được khuyến nghị để xử lý các địa chỉ hoàn toàn không có cấu trúc (thay vì đoán phần nào của địa chỉ sẽ là thành phố 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 API 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à sẽ 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 API 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à sẽ không được trả về trong phản hồi.

LanguageOptions

Bản xem trước: Tính năng này đang ở giai đoạn thử nghiệm (trước giai đoạn phát hành rộng rã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ể đượ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. Sản phẩm trước giai đoạn phát hành rộng rãi phải tuân thủ Đ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.

Bật 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ả của việc xác thực một đị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 việc giao hàng. metadata không được đảm bảo sẽ được điền đầy đủ dữ liệu cho mọi địa chỉ được gửi đến API xác thực địa chỉ.
uspsData

object (UspsData)

Cờ giao hàng bổ sung do USPS cung cấp. Chỉ được cung cấp ở khu vực US và PR.
englishLatinAddress

object (Address)

Bản xem trước: Tính năng này đang ở giai đoạn thử nghiệm (trước giai đoạn phát hành rộng rã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ể đượ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. Sản phẩm trước giai đoạn phát hành rộng rãi phải tuân thủ Đ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ỉ này được dịch sang tiếng Anh.

Không thể sử dụng lại các địa chỉ đã dịch làm dữ liệu đầu vào của API. Dịch vụ này cung cấp các mã này để người dùng có thể sử dụng ngôn ngữ bản địa của họ để 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. Xem tại đây để xem nội dung giải thích về cách ngôn ngữ thay thế được chọn. 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 các trường englishLatinAddress và 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ý ở cấp độ cao.

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)

Độ 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. Để biết 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ỉ nhập chứa 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ệ, validationGranularity có thể sẽ có giá trị là PREMISE hoặc thấp hơn.
validationGranularity

enum (Granularity)

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

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ề mức độ chi tiết của geocode. Điều này có thể được hiểu là ý nghĩa ngữ nghĩa của mức độ tương đối hoặc chi tiết của vị trí được mã hoá địa lý.

Điều này đôi khi 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 lại sự tồn tại của 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 giải quyết, không có thành phần địa chỉ bị thiếu hoặc không mong muốn nào. 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.
hasUnconfirmedComponents

boolean

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, hãy xem google.maps.addressvalidation.v1.Address.address_components để biết 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ế, vui lòng xem google.maps.addressvalidation.v1.Address.address_components để biết thông tin chi tiết.

Độ chi tiết

Nhiều chi tiết khác nhau mà một địa chỉ hoặc một mã địa lý có thể có. Khi 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 được một địa chỉ gửi thư. Ví dụ: địa chỉ chẳng hạn như "123 Main Street, Redwood City, CA, 94061" xác định PREMISE trong khi có nội dung như "Redwood City, CA, 94061" xác định một LOCALITY. Tuy nhiên, nếu chúng tôi không thể tìm thấy mã địa lý cho "123 Main Street" ở Redwood City, mã địa lý được trả về có thể có độ chi tiết LOCALITY mặc dù địa chỉ chi tiết 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ả tìm kiếm bên dưới tầng toà nhà, chẳng hạn như một căn hộ.
PREMISE Kết quả cấp toà nhà.
PREMISE_PROXIMITY Một mã địa lý gần đúng vị trí cấp toà nhà của địa chỉ.
BLOCK Địa chỉ hoặc mã địa lý biểu thị một khối. Chỉ dùng ở các 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ỉ là chi tiết đối với tuyến đường, chẳng hạn như đường, đường hoặc đường cao tốc.
OTHER Tất cả các chi tiết khác, được nhóm lại với nhau vì chúng không thể gửi được.

Địa chỉ

Thông tin chi tiết về địa chỉ sau khi xử lý. Xử lý hậu kỳ bao gồm sửa các phần sai chính tả của địa chỉ, thay thế các bộ 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ỉ sau xử lý, có định dạng là địa chỉ một dòng tuân theo các quy tắc định dạng địa chỉ của khu vực đặt địa chỉ đó.
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ỉ đã đị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ể. Không giả định về thứ tự của các thành phần địa chỉ trong danh sách.
missingComponentTypes[]

string

Những loại thành phần dự kiến sẽ xuất hiện 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 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

Loại thành phần có trong addressComponents nhưng không thể xác nhận 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 tài sản 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à phần hợp lệ của một địa chỉ (ví dụ: trong giá trị nhập như "123235253253 Main St, San Francisco, CA, 94105", mã thông báo chưa được giải quyết có thể có dạng ["123235253253"] vì mã đó trông không hợp lệ.

AddressComponent

Đại diện cho một thành phần địa chỉ, chẳng hạn như đường, 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 cho 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 của chúng tôi về việc thành phần này 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 thông tin đầu vào, nhưng chúng tôi đã suy luận cho vị trí địa chỉ và cho rằng thành phần này nên được cung cấp cho một địa chỉ đầy đủ.
spellCorrected

boolean

Cho biết đã 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 một biến thể chính tả khác, chẳng hạn như khi thay đổi "giữa" thành "chính giữa". Tính năng này cũng không phải lúc nào cũng gắn cờ các lỗi chính tả phổ biến, chẳng hạn như khi thay đổi "AmphitThermal Pkwy" thành "Amphitheatre 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 bị thay thế sai bằng một mã địa chỉ chính xác. Đây không phải là thay đổi mang tính thẩm mỹ, 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 thành phần địa chỉ dự kiến sẽ không xuất hiện trong một địa chỉ bưu chính cho khu vực cụ thể. Chúng tôi chỉ giữ lại đoạn mã này vì nó là một phần của dữ liệu đầu vào.

ComponentName

Một 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" cho tên đường phố hoặc "1253" cho 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ể sử dụng cho các cấp xác nhận.

Enum
CONFIRMATION_LEVEL_UNSPECIFIED Giá trị mặc định. Giá trị này chưa được sử dụng.
CONFIRMED Chúng tôi có thể xác minh rằng thành phần này tồn tại và có ý nghĩa trong ngữ 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ể xác nhận sự tồn tại của thành phần này. Ví dụ: số nhà nằm trong một phạm vi các số hợp lệ đã biết trên một con phố 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ó khả năng là không chính xác. Ví dụ: một vùng lân cận 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ề vị trí mà đầ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 đầu vào.

Bạn nên sử dụng mã địa điểm so với việc sử dụng địa chỉ, vĩ độ/kinh độ hoặc mã cộng. Việc sử dụng toạ độ khi định tuyến hoặc tính toán chỉ đường lái xe sẽ luôn dẫn đến việc điểm bị gắn với đường gần các toạ độ đó nhất. Đây không phải là đường sẽ dẫn tới điểm đến một cách nhanh chóng hoặc an toàn và có thể không nằm 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ả về sẽ khớp với địa chỉ ban đầu.
plusCode

object (PlusCode)

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

object (Viewport)

Giới hạn 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 phép đo khác về độ tương đối của vị trí được mã hoá địa lý, nhưng về kích thước vật lý chứ không phải là về nghĩa ngữ nghĩa.
placeId

string

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

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

string

(Các) Loại địa điểm mà đầ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ị bằ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 1/8000 x 1/8000 độ (~ 14 x 14 mét).
compoundCode

string

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

Khung nhìn

Khung nhìn vĩ độ – kinh độ, được biểu thị bằng hai đường chéo đối diện điểm low và high. Một khung nhìn được xem là một khu vực đóng, tức là khu vực đó bao gồm cả ranh giới của nó. 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 chỉ bao gồm một điểm duy nhất đó.

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

  • Nếu low.longitude = -180 độ và high.longitude = 180 độ, khung nhìn sẽ bao gồm tất cả cá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ĩ độ bị 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 quanh hoàn toàn 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ỉ. metadata không được đảm bảo sẽ được điền đầy đủ dữ liệu 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 rằng đây là địa chỉ của một doanh nghiệp. Nếu bạn không đặt chính sách này thì tức là giá trị là không xác định.
poBox

boolean

Cho biết rằng địa chỉ của hộp thư bưu điện. Nếu bạn không đặt chính sách này thì tức là giá trị là 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 bạn không đặt chính sách này thì tức là giá trị là không xác định.

UspsData

Dữ liệu của USPS cho địa chỉ. Chúng tôi không đảm bảo rằng uspsData sẽ được điền đầy đủ dữ liệu cho mọi địa chỉ ở Hoa Kỳ hoặc địa chỉ ở Quan hệ công chúng được gửi đến API Xác thực địa chỉ. Bạn nên tích hợp các trường địa chỉ dự phòng vào 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 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 sẽ được thêm vào cuối delivery_point_barcode đối với thư được quét bằng phương pháp cơ học. 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ể sử dụng để xác nhận DPV. Trả về một ký tự hoặc không trả về giá trị nào.

  • N: Không thể xác nhận thông tin về số chính và mọi thông tin phụ về DPV.
  • 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ụ.
  • S: Địa chỉ đã được xác nhận DPV cho số điện thoại chính và thông tin về số phụ đã xuất hiện nhưng chưa được xác nhận.
  • Y: Địa chỉ đã được xác nhận DPV cho các 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 cuối trang từ quy trình xác thực điểm giao hàng. Nhiều chú thích cuối trang có thể được xâu chuỗi 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ố phụ không khớp và không bắt buộc
  • C1: Số phụ không khớp nhưng bắt buộc
  • N1: Địa chỉ cao tầng thiếu số phụ
  • M1: Thiếu số chính
  • M3: Số chính không hợp lệ
  • P1: Thiếu số hộp PO, RR hoặc HC của địa chỉ nhập
  • P3: Địa chỉ nhập PO, RR hoặc HC Số hộp không hợp lệ
  • F1: Địa chỉ nhập khớp với địa chỉ quân đội
  • 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ã ZIP 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ỉ đã được xác nhận DPV nhưng không có thông tin về PMB
  • R7: Bản ghi R777 hoặc R779 của hãng hàng không
  • 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ông ty nhận thư thương mại) 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à một CMRA
  • N: Địa chỉ không phải là CMRA
dpvVacant

string

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

  • Y: Địa chỉ còn trống
  • N: Địa chỉ còn trống
dpvNoStat

string

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

  • 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 số nguyên.

  • 1: IDA (Địa chỉ gửi thư nội bộ) – Các địa chỉ không nhận thư trực tiếp từ USPS nhưng được gửi đến địa chỉ thả thư phục vụ các địa chỉ đó.
  • 2: CDS – Các địa chỉ chưa thể giao được. 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 sự và các loại hình khác) – Mã ZIP + 4 hồ sơ mà USPS đã đưa vào dữ liệu.
  • 5: Thường xuyên – Cho biết các địa chỉ không nhận được thư và các địa chỉ này không được tính là địa chỉ giao hàng có thể thực hiện.
  • 6: Bắt buộc phải có thông tin phụ – Địa chỉ này phải có thông tin phụ.
dpvDrop

string

Cờ cho biết thư được gửi đến một nơi có thể nhận tại một trang web. Trả về một ký tự đơn.

  • Y: Thư được gửi đến một nơi có thể nhận tại một trang web.
  • N: Thư không được gửi tới một nơi có thể nhận 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ự đơn.

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

string

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

  • 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ó chỉ báo rằng việc gửi thư không được thực hiện tất cả các ngày trong tuần.
dpvNonDeliveryDaysValues

integer

Số nguyên xác định số ngày không phân phối. Có thể điều tra 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 0x01
dpvNoSecureLocation

string

Cờ cho biết có thể vào cửa, nhưng gói hàng sẽ không bị để lại do vấn đề bảo mật. Trả về một ký tự đơn.

  • Y: Gói sẽ không được để lại do lo ngại về bảo mật.
  • N: Không có chỉ báo rằng gói sẽ không được để lại do vấn đề bảo mật.
dpvPbsa

string

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

  • 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ự đơn.

  • Y: Không thể vào cửa.
  • N: Không có chỉ báo là không thể vào cửa.
dpvEnhancedDeliveryCode

string

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

  • Y: Địa chỉ đã được xác nhận DPV cho các số chính và mọi số phụ.
  • N: Không thể xác nhận thông tin về số chính và mọi thông tin phụ về DPV.
  • S: Địa chỉ được xác nhận DPV chỉ cho số chính và thông tin về số phụ đã xuất hiện nhưng không được xác nhận hoặc một alpha cuối của số chính đã bị loại bỏ để khiến DPV trùng khớp 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 chỉ định cho tuyến ảo R777 và R779 cũng như không cung cấp dịch vụ giao hàng USPS.
carrierRoute

string

Mã tuyến của nhà mạng. 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 đường của hãng vận chuyển (hoặc tuyến thành phố)
  • R: Tuyến đường nông thôn
  • H: Tuyến đường hợp đồng trên đường cao tốc
  • B: Mục 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ể khớp, nhưng tệp EWS cho thấy sẽ sớm có kết quả khớp chính xác.
postOfficeCity

string

Thành phố của 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 FIPS.
county

string

Tên hạt.
elotNumber

string

Số tuyến du lịch nâng cao (eLOT).
elotFlag

string

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

boolean

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

string

Người chỉ định đơn vị PMB (Hộp thư cá nhân).
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ỉ đã nhập.

  • F: TÌNH HUỐNG. Đây là kết quả trùng khớp với Bản ghi của công ty, đây là mức độ trùng khớp cao nhất hiện có cho một địa chỉ.
  • G: PHÂN PHỐI CHUNG. Dữ liệu này khớp với một Hồ sơ phân phối chung.
  • H: TÒA NHÀ / CĂN HỘ. Dữ liệu này trùng khớp với một bản ghi về Toà nhà hoặc Căn hộ.
  • P: HỘP SAU KHI ĐĂNG KÝ. Mã này 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ó địa chỉ cụ thể hơn.
errorMessage

string

Thông báo lỗi về việc truy xuất dữ liệu USPS. Thông tin này được điền sẵn khi quá trình xử lý USPS bị tạm ngưng do phát hiện thấy các địa chỉ được tạo giả tạo.

Các trường dữ liệu USPS có thể không được điền sẵn khi xuất hiện lỗi này.
cassProcessed

boolean

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

UspsAddress

USPS đại diện cho một địa chỉ ở Hoa Kỳ.

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á tại 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.