Method: geocode.destinations.searchDestinations

Phương thức này thực hiện một thao tác tra cứu đích đến và trả về danh sách các đích đến.

Yêu cầu HTTP

POST https://geocode.googleapis.com/v4alpha/geocode/destinations

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 
{
  "travelModes": [
    enum (NavigationPoint.TravelMode)
  ],
  "languageCode": string,
  "regionCode": string,

  // Union field primary_query can be only one of the following:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of list of possible types for union field primary_query.
}
Trường
travelModes[]

enum (NavigationPoint.TravelMode)

Không bắt buộc. Các chế độ di chuyển để lọc các điểm điều hướng. Điều này ảnh hưởng đến trường navigationPoints được trả về trong phản hồi. Nếu trống, bạn có thể nhận được các điểm điều hướng của tất cả phương tiện đi lại.
languageCode

string

Không bắt buộc. Ngôn ngữ mà kết quả sẽ được trả về.
regionCode

string

Không bắt buộc. Mã vùng. Mã khu vực, được chỉ định dưới dạng giá trị gồm 2 ký tự ccTLD ("miền cấp cao nhất"). Tham số này ảnh hưởng đến kết quả dựa trên luật hiện hành. Tham số này cũng ảnh hưởng (nhưng không hạn chế hoàn toàn) đến kết quả của dịch vụ.

Trường nhóm primary_query. Truy vấn điểm đến chính. Đây có thể là một địa điểm, một địa chỉ được chỉ định đầy đủ hoặc một vị trí LatLng. Một số địa điểm và địa chỉ có ít thông tin sẽ không thể chuyển thành điểm đến.

Các đích đến được xây dựng dựa trên cụm từ tìm kiếm chính đã chỉ định.

Lưu ý: chỉ những địa điểm và địa chỉ có thể có đích đến điều hướng mới được hỗ trợ. Ví dụ: bạn có thể dùng một địa điểm đại diện cho một ngôi nhà hoặc khu chung cư làm cụm từ tìm kiếm chính, nhưng không thể dùng những địa điểm đại diện cho một địa phương hoặc khu vực hành chính làm cụm từ tìm kiếm chính. primary_query chỉ có thể là một trong những trạng thái sau:
place

string

Tên tài nguyên của một địa điểm, ở định dạng places/{placeId}.
addressQuery

object (SearchDestinationsRequest.AddressQuery)

Địa chỉ đường phố.
locationQuery

object (SearchDestinationsRequest.LocationQuery)

Vị trí chính xác.

Nội dung phản hồi

Thông báo phản hồi cho DestinationService.SearchDestinations.

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 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
Trường
destinations[]

object (Destination)

Danh sách các đích đến.

Dịch vụ này trả về một kết quả nếu có thể xác định rõ ràng một đích đến chính từ truy vấn chính. Nếu không, dịch vụ có thể trả về nhiều kết quả để phân biệt hoặc không có kết quả nào.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/maps-platform.geocode

SearchDestinationsRequest.AddressQuery

Địa chỉ đường phố mà bạn muốn tìm kiếm. Hãy chỉ định địa chỉ theo định dạng mà dịch vụ bưu chính quốc gia của quốc gia liên quan sử dụng.

Biểu diễn dưới dạng JSON 
{

  // Union field kind can be only one of the following:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of list of possible types for union field kind.
}
Trường
Trường nhóm kind. Truy vấn địa chỉ. kind chỉ có thể là một trong những trạng thái sau:
address

object (PostalAddress)

Địa chỉ đường phố ở định dạng địa chỉ bưu chính.
addressQuery

string

Địa chỉ đường phố được định dạng thành một dòng duy nhất.

SearchDestinationsRequest.LocationQuery

Một truy vấn vị trí để xác định đích đến chính ở gần.

Lưu ý: nếu truy vấn vị trí nằm trong một toà nhà có chứa các cơ sở phụ, thì có thể địa điểm chính được trả về là một cơ sở phụ. Trong những trường hợp này, trường containingPlaces sẽ bao gồm cả toà nhà.

Biểu diễn dưới dạng JSON 
{

  // Union field kind can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field kind.
}
Trường
Trường nhóm kind. Cụm từ tìm kiếm vị trí. kind chỉ có thể là một trong những trạng thái sau:
location

object (LatLng)

Vị trí LatLng chính xác.

Đích đến

Một điểm đến. Điều này bao gồm địa điểm chính, các địa điểm liên quan, lối vào và điểm điều hướng.

Biểu diễn dưới dạng JSON 
{
  "primary": {
    object (PlaceView)
  },
  "containingPlaces": [
    {
      object (PlaceView)
    }
  ],
  "subDestinations": [
    {
      object (PlaceView)
    }
  ],
  "landmarks": [
    {
      object (Landmark)
    }
  ],
  "entrances": [
    {
      object (Entrance)
    }
  ],
  "navigationPoints": [
    {
      object (NavigationPoint)
    }
  ]
}
Trường
primary

object (PlaceView)

Địa điểm chính do primary_query xác định trong yêu cầu.
containingPlaces[]

object (PlaceView)

Những địa điểm ít chính xác hơn mà địa điểm chính nằm trong đó. Ví dụ: khu chung cư có toà nhà này.
subDestinations[]

object (PlaceView)

Các địa điểm phụ chính xác hơn của địa điểm chính. Ví dụ: các căn hộ trong một toà nhà.

Lưu ý: so với SubDestination do Places API trả về, danh sách các điểm đến phụ này đầy đủ hơn và mỗi điểm đến phụ đều chứa nhiều thông tin hơn.
landmarks[]

object (Landmark)

Địa danh có thể dùng để cho biết vị trí của đích đến hoặc giúp bạn đến nơi.
entrances[]

object (Entrance)

Lối vào của địa điểm này.
navigationPoints[]

object (NavigationPoint)

Các điểm điều hướng cho đích đến này.

PlaceView

Biểu thị chế độ xem Địa điểm trong Places API. Ngoài ra, thông tin này cũng cung cấp thêm thông tin cụ thể về các điểm đến, chẳng hạn như loại cấu trúc và đa giác hiển thị.

Trong một số trường hợp, PlaceView có cùng mã địa điểm có thể khác với mã địa điểm mà Places API trả về cho các trường types và displayName.

Biểu diễn dưới dạng JSON 
{
  "place": string,
  "displayName": {
    object (LocalizedText)
  },
  "primaryType": string,
  "types": [
    string
  ],
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "structureType": enum (PlaceView.StructureType),
  "location": {
    object (LatLng)
  },
  "displayPolygon": {
    object
  }
}
Trường
place

string

Tên tài nguyên của địa điểm này, ở định dạng places/{placeId}.
displayName

object (LocalizedText)

Nội dung mô tả địa điểm mà con người có thể đọc được. Ví dụ: "Cổng B", "McDonalds"
primaryType

string

Loại địa điểm chính của địa điểm này. Hãy xem https://developers.google.com/maps/documentation/places/web-service/place-types để biết danh sách các giá trị có thể có.

Lưu ý: Trường này không phải lúc nào cũng được điền sẵn. Hãy chuẩn bị sử dụng trường types trong những trường hợp như vậy.
types[]

string

Tất cả các loại địa điểm được liên kết với địa điểm này. Hãy xem https://developers.google.com/maps/documentation/places/web-service/place-types để biết danh sách các giá trị có thể có.
formattedAddress

string

Địa chỉ trên một dòng.
postalAddress

object (PostalAddress)

Địa chỉ có cấu trúc.
structureType

enum (PlaceView.StructureType)

Loại cấu trúc tương ứng với địa điểm này.
location

object (LatLng)

Vị trí của địa điểm này. Đối với những địa điểm có đa giác hiển thị, đây có thể là một vị trí phù hợp để đặt điểm đánh dấu trên bản đồ.
displayPolygon

object (Struct format)

Đường viền đa giác của địa điểm ở định dạng GeoJSON, sử dụng định dạng RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6.

Lưu ý: Định dạng RFC 7946 hỗ trợ MultiPolygon, vì vậy, một đối tượng displayPolygon có thể biểu thị nhiều đa giác.

PlaceView.StructureType

Loại cấu trúc mà địa điểm này đại diện.

Enum
STRUCTURE_TYPE_UNSPECIFIED Không được dùng.
POINT Vị trí điểm.
SECTION Một phần của toà nhà.
BUILDING Một toà nhà.
GROUNDS Một khu vực rộng lớn thường có nhiều toà nhà, chẳng hạn như khuôn viên trường đại học, khu phức hợp căn hộ hoặc trung tâm mua sắm.

Địa danh

Địa danh được dùng để cho biết vị trí của đích đến hoặc giúp bạn đến được đích đến.

Biểu diễn dưới dạng JSON 
{
  "tags": [
    enum (Landmark.Tag)
  ],

  // Union field landmark can be only one of the following:
  "place": {
    object (PlaceView)
  }
  // End of list of possible types for union field landmark.
}
Trường
tags[]

enum (Landmark.Tag)

Các thẻ mô tả cách sử dụng địa điểm nổi tiếng trong bối cảnh của đích đến.
Trường nhóm landmark. Địa danh. landmark chỉ có thể là một trong những trạng thái sau:
place

object (PlaceView)

Địa điểm đại diện cho địa danh này.

Landmark.Tag

Danh sách tất cả các thẻ có thể mô tả cách sử dụng một địa danh trong bối cảnh của một đích đến.

Nếu một địa chỉ có cả thẻ ADDRESS và ARRIVAL, thì tức là địa danh đó vừa nổi bật tại địa phương vừa gần với đích đến.

Enum
TAG_UNSPECIFIED Không được dùng.
ADDRESS Một địa điểm nổi bật tại địa phương có thể được dùng để xác định vị trí chung của đích đến. Thường là trong vòng vài trăm mét tính từ điểm đến. Những địa điểm này tương tự như các địa điểm nổi tiếng do tính năng Bộ mô tả địa chỉ của Geocoding API trả về: https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors.
ARRIVAL Một địa điểm có thể được dùng để giúp bạn đến được đích đến. Hữu ích cho việc điều hướng khi bạn đến gần điểm đến. Ví dụ: địa danh này có thể là một nơi nằm bên kia đường so với điểm đến. Địa điểm có thẻ này thường gần đích đến hơn so với địa điểm có thẻ ADDRESS.

Lối vào

Lối vào là một cặp toạ độ vĩ độ/kinh độ duy nhất xác định vị trí của điểm vào và điểm ra của một địa điểm.

Biểu diễn dưới dạng JSON 
{
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
Trường
location

object (LatLng)

Vị trí của lối vào.
tags[]

enum (Entrance.Tag)

Danh sách các thẻ mô tả lối vào.
place

string

Cấu trúc mà lối vào này nằm trên đó, ở định dạng places/{placeId}.

Entrance.Tag

Đặc điểm mô tả một lối vào.

Enum
TAG_UNSPECIFIED Không được dùng.
PREFERRED

Lối vào này có thể giúp bạn đến được địa điểm chính trong đích đến được trả về. Một địa điểm có thể có nhiều lối vào ưu tiên. Nếu một lối vào không có thẻ này, tức là lối vào đó nằm trong cùng toà nhà với địa điểm chính, nhưng không nhất thiết phải có lối vào địa điểm đó.

Ví dụ: nếu địa điểm chính là một nhà hàng trong một khu mua sắm, thì các lối vào "ƯU TIÊN" sẽ là những lối vào có khả năng dẫn vào chính nhà hàng đó, trong khi các lối vào khác được trả về sẽ là những lối vào khác của toà nhà, chẳng hạn như lối vào các nhà hàng khác trong khu mua sắm.

Nếu địa điểm chính là một toà nhà, thì PREFERRED lối vào sẽ là những lối dẫn vào phần "chính" của toà nhà. Ví dụ: trong một trung tâm mua sắm, các lối vào PREFERRED sẽ là những lối vào cho phép bạn đi vào khu vực sảnh chính, nhưng nếu một lối vào chỉ cho phép bạn đi vào một cửa hàng ở bên hông toà nhà, thì đó sẽ không phải là lối vào PREFERRED.

Lưu ý: Lối vào có biểu tượng PREFERRED có thể không dẫn đến địa điểm chính, còn lối vào không có biểu tượng PREFERRED có thể dẫn đến địa điểm chính.