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 được định dạng qua addressLines.

Tổng độ dài của các trường trong mục nhập 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ỉ nhập được dành riêng cho mục đích sử dụng sau này và sẽ bị bỏ qua ngay hôm nay. Kết quả xác thực địa chỉ 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.

API xác thực địa chỉ bỏ qua các giá trị trong recipientsorganization. Mọi giá trị trong các trường đó đều 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 cho yêu cầu xác thực địa chỉ đầu tiên. Nếu cần thêm 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 sẵn responseId vào trường này bằng responseId ngay 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 các yêu cầu có bật CASS của USPS cho các đị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 cung cấp google.type.PostalAddress.administrative_area của address dưới dạng "Puerto Rico" (không phân biệt chữ hoa chữ thường) hoặc "PR".

Bạn nên dùng address được thành phần hoá 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 đường, 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 Xem trước (trước giai đoạn phát hành rộng rã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ể bị hỗ trợ hạn chế. Đồng thời, các 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 khác 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 chịu sự điều chỉnh của Điều khoản dành riêng cho 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.

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 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, có độ dài tối đa là 36 ký tự ASCII. Nếu không, hệ thống sẽ trả về lỗi INVALID_ qu.

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 một cuộc gọi đến Chi tiết địa điểm hoặc Xác thực đị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 Thông tin chi tiết về địa điểm hoặc Yêu cầu xác thực địa chỉ. Thông tin đăng nhập được dùng cho từng yêu cầu trong một phiên phải thuộc cùng một dự án trên Google Cloud Console. Sau khi một phiên kết thúc, mã thông báo này không còn hợp lệ nữa. Ứng dụng phải tạo một mã thông báo mới cho mỗi phiên. Nếu tham 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 hoạt động 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ể 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 phải API Tự động hoàn thành. Hãy tham khảo tại 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 một 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ả của việc 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ì UUID này phải đi kèm với yêu cầu mới.

PostalAddress

Đại diện cho một địa chỉ bưu chính, ví dụ như địa chỉ giao hàng hoặc địa chỉ thanh toán. Với một địa chỉ bưu chính, dịch vụ bưu chính có thể giao các mặt hàng đến một địa chỉ, hộp thư bưu điện hoặc những mặt hàng tương tự. Công cụ này không nhằm mô hình hoá vị trí địa lý (đường, thị trấn, núi).

Trong cách sử dụng thông thường, đị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ỉ có thể 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 những quốc gia nơi trường đó được sử dụng.

Để được hướng dẫn thêm 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 đều 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/vùng địa chỉ. Xem https://cldr.unicode.org/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, hệ thống sẽ suy ra mã vùng từ địa chỉ. Để có hiệu suất tốt nhất, bạn nên thêm mã vùng nếu bạn biết mã vùng đó. 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, đừng cung cấp lại mã vùng trong trường này. Bạn có thể tìm thấy 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 cho mục đích sử dụng sau này và sẽ bị bỏ qua ngay hôm nay. API sẽ trả về địa chỉ bằng ngôn ngữ thích hợp cho nơi đặt đị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. Tuy nhiên, nếu mã bưu chính được sử dụng, chúng 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 ở Hoa Kỳ).

sortingCode

string

Không bắt buộc. Mã phân loại bổ sung theo quốc gia. Thông tin này không được sử dụng ở hầu hết các khu vực. Trong trường hợp 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 con 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 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 được dùng cho các địa chỉ bưu chính của một quốc gia hoặc khu vực. Ví dụ: đây có thể là 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 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 thông tin này.

locality

string

Không bắt buộc. Nói chung đề cập đến phần thành phố/thị trấn của địa chỉ. Ví dụ: Thành phố ở Hoa Kỳ, thị xã CNTT, thị trấn có bưu điện ở Vương quốc Anh. Ở các khu vực trên thế giới nơi đị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 địa chỉ AddressLine.

sublocality

string

Không bắt buộc. Quận/phường của địa chỉ. Ví dụ: đây có thể là các vùng lân cận, thị xã, quận.

addressLines[]

string

Bắt buộc. Dòng địa chỉ không có 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 AddressLine 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"), thì điều quan trọng là thứ tự dòng phải 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ỉ.

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

Tạo địa chỉ chỉ chứa addressLines và sau đó mã hóa địa lý là cách được đề xuất để xử lý các địa chỉ hoàn toàn không có cấu trúc (thay vì phải đoán phần nào của địa chỉ phải 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 chưa sử dụng tính năng 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 chưa sử dụng tính năng 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 xem trước: Tính năng này đang ở giai đoạn Xem trước (trước giai đoạn phát hành rộng rã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ể bị hỗ trợ hạn chế. Đồng thời, các 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 khác 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 chịu sự điều chỉnh của Điều khoản dành riêng cho 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.

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

Bản 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 đị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ờ 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ý đến.

metadata

object (AddressMetadata)

Thông tin khác liên quan đến khả năng phân phối. Google không đảm bảo rằng metadata 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ờ khả năng giao bổ sung do USPS cung cấp. Chỉ được cung cấp ở khu vực USPR.

englishLatinAddress

object (Address)

Bản xem trước: Tính năng này đang ở giai đoạn Xem trước (trước giai đoạn phát hành rộng rã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ể bị hỗ trợ hạn chế. Đồng thời, các 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 khác 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 chịu sự điều chỉnh của Điều khoản dành riêng cho 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.

Đị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ụ này cung cấp những thông tin đó để người dùng có thể sử dụng ngôn ngữ bản địa của mình để xác nhận hoặc từ chối xác thực địa chỉ đã 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, dịch vụ sẽ trả về phần đó bằng ngôn ngữ thay thế có sử dụng chữ viết Latinh. Vui lòng xem tại đây để biết nội dung giải thích về cách hệ thống lựa 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 bằng ngôn ngữ sử dụng chữ viết Latinh, 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 kết quả 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à các 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 cấp cao 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)

Độ chi tiết của địa chỉ đầu vào. Đây là kết quả của việc phân tích cú pháp địa chỉ nhập và không cung cấp bất kỳ 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 dưới đây.

Ví dụ: nếu địa chỉ nhập bao gồm 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ể sẽ là PREMISE hoặc thấp hơn.

validationGranularity

enum (Granularity)

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

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

geocodeGranularity

enum (Granularity)

Thông tin về độ chi tiết của geocode. Điều này có thể được hiểu là ý nghĩa ngữ nghĩa cho biết vị trí được mã hoá địa lý kém hay nhỏ.

Đ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 chung cư 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ỉ nào không mong muốn hoặc bị thiếu. Nếu không được đặt, hãy cho biết giá trị là false. Xem các trường missingComponentTypes, unresolvedTokens hoặc unexpected để biết thêm thông tin.

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 ra (được thêm) không có trong dữ liệu nhập, 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ế, hãy xem google.maps.addressvalidation.v1.Address.address_components để biết thông tin chi tiết.

Độ chi tiết

Chi tiết khác nhau mà một địa chỉ hoặc một mã địa lý có thể có. Khi dùng để biểu thị mức độ chi tiết của một địa chỉ, các giá trị này sẽ thể hiện mức độ chi tiết của địa chỉ xác định một điểm đến 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 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 không được sử dụng.
SUB_PREMISE Kết quả có cấp độ toà nhà thấp hơn, 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ý ước chừ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ỉ đượ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 đố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ể phân phối được.

Address (Địa chỉ)

Thông tin chi tiết về địa chỉ được xử lý sau. Xử lý hậu kỳ bao gồm sửa những phần 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 còn 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 dưới dạng địa chỉ một dòng tuân theo các quy tắc định dạng địa chỉ của khu vực nơi đặ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ự. 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. Cột 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

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 mục nhập VÀ không thể suy ra đượ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 đầu vào như "Boulder, Colorado, 80301, USA". Bạn có thể xem danh sách các loại 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 thể được 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 này tương đương với việc lặp lại qua addressComponents để tìm loại 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

Bất kỳ mã thông báo nào trong dữ liệu đầu vào 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ụ: trong dữ liệu đầu vào 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ì số đó không phải là số đườ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 mà chúng tôi có được rằng thành phần đó là chính xác.

inferred

boolean

Cho biết rằng thành phần này không nằm trong dữ liệu đầu vào, nhưng chúng tôi đã suy luận thành phần này dựa trên vị trí của địa chỉ và cho rằng thành phần này nên được cung cấp để có 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ừ biến thể chính tả này sang biến thể khác, chẳng hạn như khi thay đổi "centre" thành "center". Trang 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 "Amphitheater Pkwy" thành "Amphitheaterre Pkwy".

replaced

boolean

Cho biết tên của thành phần đã được thay thế bằng một thành phần hoàn toàn khác, ví dụ: mã bưu chính sai được thay thế bằng mã đúng cho địa chỉ. Đâ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 địa chỉ bưu chính của khu vực đã cho. Chúng tôi chỉ giữ lại dữ liệu này vì đó 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" cho tên đường hoặc "1253" cho số nhà.

languageCode

string

Mã ngôn ngữ BCP-47. Thuộc tính này sẽ không xuất hiện nếu tên thành phần không 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ác 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 có thể xác minh rằng thành phần này tồn tại và phù hợp 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 được rằng nó tồn tại. Ví dụ: số nhà nằm trong một dãy 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ó thể 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ề địa điểm mà dữ liệu đầu vào được mã hoá địa lý đến.

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.

Sử dụng mã địa điểm được ưu tiên hơn sử dụng địa chỉ, vĩ độ/kinh độ hoặc mã cộng. Sử dụng toạ độ khi định tuyến hoặc tính toán chỉ đường lái xe sẽ luôn gắn kết điểm với con đường gần với các toạ độ đó nhất. Đây có thể không phải là đường dẫn tới điểm đến một cá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ý ngược, chúng tôi không đảm bảo rằng địa chỉ được trả về sẽ khớp với địa chỉ ban đầu.

plusCode

object (PlusCode)

Mã cộng tương ứng với location.

bounds

object (Viewport)

Các 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ề độ thô của vị trí được mã hoá địa lý, nhưng theo kích thước vật lý thay vì theo ý nghĩa ngữ nghĩa.

placeId

string

Mã địa điểm của nơi nhập mã địa lý tới.

Để 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ý đến. Ví dụ: ['locality', 'political']. Bạn có thể xem danh sách đầy đủ các loại thuộc tính tại đây.

LatLng

Một đối tượng đại diện cho cặp vĩ độ/kinh độ. Thuộc tính này được biểu thị dưới dạng một cặp đôi đạ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 theo độ. Giá trị phải nằm trong phạm vi [-90.0, +90.0].

longitude

number

Kinh độ tính theo độ. Giá trị phải nằm trong phạm vi [-180.0, +180.0].

PlusCode

Mã cộng (http://plus.codes) là một mã tham chiếu vị trí có hai định dạng: mã chung xác định một hình chữ nhật có kích thước 14 m x 14 m (1/8000 độ) hoặc nhỏ hơn và mã phức hợp, thay thế tiền tố bằng một 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 tỷ lệ 1/8000 x 1/8000 độ khu vực (~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ã chung và thay thế tiền tố bằng tên đã định dạng của một thực thể tham chiếu.

Khung nhìn

Một chế độ xem kinh độ – vĩ độ, được thể hiện dưới dạng hai điểm theo đường chéo đối diện lowhigh. Khung nhìn được xem là một khu vực khép kín, tức là nó bao gồm 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ác trường hợp khác nhau bao gồm:

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

  • Nếu low.longitude > high.longitude, 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ả các kinh độ.

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

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

Cả lowhigh đều phải được điền và không được để trống hộp được đại diện (như được chỉ định trong các định nghĩa ở trên). Khung nhìn trống sẽ gây ra lỗi.

Ví dụ: khung nhìn này bao quanh đầy đủ 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 cho địa chỉ. Google không đảm bảo rằng metadata 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ì hệ thống sẽ cho biết rằng 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ì hệ thống sẽ cho biết rằng 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ì hệ thống sẽ cho biết rằng giá trị là không xác định.

UspsData

Dữ liệu USPS cho địa chỉ. Google 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 PR được gửi tới API xác thực địa chỉ. Bạn nên tích hợp các trường địa chỉ sao lưu 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á theo USPS.

deliveryPointCode

string

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

deliveryPointCheckDigit

string

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

dpvConfirmation

string

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

  • N: Không xác nhận được thông tin về số chính và mọi thông tin về số phụ.
  • D: Địa chỉ đã được DPV xác nhận chỉ 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 DPV chỉ xác nhận cho số điện thoại chính, và thông tin về số điện thoại phụ đã xuất hiện nhưng chưa được xác nhận.
  • Y: Địa chỉ đã được xác nhận là DPV cho các số chính và các số phụ.
  • Trống: Nếu phản hồi không chứa giá trị dpvConfirmation, tức là địa chỉ chưa được gửi để xác nhận DPV.
dpvFootnote

string

Chú thích cuối trang từ xác thực điểm phân phối. 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ỉ nhà 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 địa chỉ nhập PO, RR hoặc số hộp HC
  • P3: Địa chỉ nhập PO, RR hoặc Số hộp HC 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ã bưu chính duy nhất
  • PB: Địa chỉ nhập khớp với bản ghi PBSA
  • RR: Địa chỉ đã xác nhận của DPV với thông tin của PMB
  • R1: Địa chỉ đã xác nhận của DPV mà không có thông tin của PMB
  • R7: Bản ghi R777 hoặc R779 của nhà mạng
  • IA: Đã xác định được địa chỉ đã nhận thông tin
  • TA: Số chính được khớp bằng cách bỏ dấu 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) 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à 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ỉ bị bỏ trống
  • N: Địa chỉ không bị bỏ trống
dpvNoStat

string

Đây là địa chỉ không có dữ liệu thống kê hay địa chỉ đang hoạt động? Không có địa chỉ thống kê nào là những địa chỉ không có người sử dụng liên tục hoặc các đị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 int.

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

string

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

  • Y: Thư được gửi đến một người nhận tại trang web.
  • N: Thư không được gửi đến một người nhận tại trang web.
dpvThrowback

string

Cho biết rằng 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 mỗi 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 mỗi ngày trong tuần.
  • N: Không có dấu hiệu cho thấy việc gửi thư không được thực hiện mỗi ngày trong tuần.
dpvNonDeliveryDaysValues

integer

Số nguyên xác định ngày không phân phối. Có thể phân phối 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 – 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 được để lại do vấn đề bảo mật. Trả về một ký tự đơn.

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

string

Cho biết địa chỉ này 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 để gửi 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 có nhiều mã trả lại DPV hợp lệ cho địa chỉ này. Trả về một ký tự đơn.

  • Y: Địa chỉ đã được xác nhận là DPV cho các số chính và các số phụ.
  • N: Không xác nhận được thông tin về số chính và mọi thông tin về số phụ.
  • S: Địa chỉ được xác nhận bằng DPV chỉ với số điện thoại chính và thông tin về số phụ xuất hiện khi chưa được xác nhận hoặc một ký tự alpha duy nhất trong số điện thoại chính đã bị loại bỏ để so khớp DPV và cần có thông tin phụ.
  • D: Địa chỉ đã được DPV xác nhận chỉ cho số điện thoại chính và thiếu thông tin về số điện thoại phụ.
  • R: Đã xác nhận địa chỉ nhưng chưa chỉ định địa chỉ cho tuyến ảo R777 và R779 và chưa cung cấp phân phối USPS.
carrierRoute

string

Mã tuyến của nhà mạng. Mã bốn ký tự bao gồm một tiền tố một chữ cái và một tên 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 đường 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: Khu hộp thư bưu điện
  • G: Đơn vị giao hàng chung
carrierRouteIndicator

string

Chỉ báo sắp xếp tốc độ tuyến đường của nhà mạng.

ewsNoMatch

boolean

Địa chỉ giao hàng có thể khớp nhưng tệp EWS cho biết rằng một kết quả khớp chính xác sẽ sớm có sẵn.

postOfficeCity

string

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

postOfficeState

string

Tiểu bang bưu điện chính.

abbreviatedCity

string

Thành phố được 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ư riêng tư).

pmbNumber

string

số PMB (Hộp thư riêng tư);

addressRecordType

string

Loại bản ghi địa chỉ khớp với địa chỉ được nhập.

  • F: FIRM. Đây là kết quả khớp với Bản ghi công ty, là mức độ so khớp tốt nhất có sẵn cho một địa chỉ.
  • G: GIAO HÀNG TỔNG HỢP. Thông tin này trùng khớp với một hồ sơ Phân phối chung.
  • H: XÂY DỰNG / CĂN HỘ. Thông tin này trùng khớp với một bản ghi về Toà nhà hoặc Căn hộ.
  • P: HỘP ĐĂNG KHUYẾN KHÍCH. Đây là kết quả phù hợp với Hộp thư bưu điện.
  • R: HỢP ĐỒNG ĐƯỜNG RỘNG hoặc HỢP ĐỒNG ĐỊA PHƯƠNG: Đây là kết quả trùng khớp với tuyến đường nông thôn hoặc hồ sơ Hợp đồng đường cao tốc, cả hai bản ghi này đều có thể có phạm vi Số hộp tương ứng.
  • S: ĐƯỜNG RECORD: Đây là kết quả trùng khớp với một bản ghi đường phố có chứa 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. Thông tin này được điền sẵn khi việc xử lý USPS bị tạm ngưng do phát hiện 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 CASS xử lý.

UspsAddress

Đại diện USPS của 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á của Puerto Rico.

cityStateZipAddressLine

string

Thành phố + tiểu bang + mã bưu điện.

city

string

Tên thành phố.

state

string

Mã trạng thái gồm 2 chữ cái.

zipCode

string

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

zipCodeExtension

string

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