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 với 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. Phương tiện đi lại để lọc điểm đi theo chỉ dẫn. Điều này ảnh hưởng đến trường navigationPoints được trả về trong phản hồi. Nếu bạn để trống, hệ thống sẽ trả về điểm đi theo chỉ dẫn 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 cho đích đế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. Bạn sẽ không thể biến một số địa điểm và địa chỉ có ít thông tin thành điểm đến.

Các đích đến được xây dựng dựa trên truy vấn 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ụ: một địa điểm đại diện cho một ngôi nhà hoặc khu chung cư có thể được dùng làm truy vấn chính, nhưng những địa điểm đại diện cho một địa phương hoặc khu vực hành chính thì không thể dùng làm truy vấn 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 sẽ 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
  • https://www.googleapis.com/auth/maps-platform.destinations

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. Cụm từ tìm kiếm địa chỉ. kind chỉ có thể là một trong những trạng thái sau:
address

object (PostalAddress)

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

string

Địa chỉ đường phố được định dạng dưới dạng một dòng.

SearchDestinationsRequest.LocationQuery

Một cụm từ tìm kiếm vị trí để xác định một điểm đế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 
{
  "placeFilter": {
    object (SearchDestinationsRequest.LocationQuery.PlaceFilter)
  },

  // 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
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

Không bắt buộc. Bộ lọc để áp dụng cho các đích đến đề xuất.
Trường nhóm kind. Cụm từ tìm kiếm về vị trí. kind chỉ có thể là một trong những trạng thái sau:
location

object (LatLng)

Vị trí chính xác theo vĩ độ và kinh độ.

SearchDestinationsRequest.LocationQuery.PlaceFilter

Bộ lọc để áp dụng cho các đích đến đề xuất.

Biểu diễn dưới dạng JSON 
{
  "structureType": enum (PlaceView.StructureType),
  "addressability": enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)
}
Trường
structureType

enum (PlaceView.StructureType)

Không bắt buộc. Nếu được chỉ định, tất cả các điểm đến đều được đảm bảo có một địa điểm chính thuộc loại cấu trúc này. Điều này có thể dẫn đến việc lọc ra một số điểm đến hoặc làm thô/tinh chỉnh các điểm đến được trả về.

Ví dụ: nếu bạn chỉ định GROUNDS, thì tất cả điểm đến được trả về sẽ có một địa điểm chính có loại cấu trúc GROUNDS. Điều này có thể dẫn đến việc lọc ra một số điểm đến không thuộc khuôn viên hoặc làm cho các điểm đến được trả về trở nên thô hơn ở cấp khuôn viên.

Một cách sử dụng khác của trường này là dễ dàng trích xuất các đa giác hiển thị toà nhà. Ví dụ: nếu bạn chỉ định BUILDING, thì đa giác hiển thị của địa điểm chính sẽ là của toà nhà tại vị trí được chỉ định.
addressability

enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)

Không bắt buộc. Nếu được chỉ định, chỉ trả về những đích đến đáp ứng tiêu chí về khả năng nhắm mục tiêu tương ứng.

PlaceView.StructureType

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

Enum
STRUCTURE_TYPE_UNSPECIFIED Không được sử dụng.
POINT Vị trí điểm.
SECTION Một phần phụ 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 chung cư hoặc trung tâm mua sắm.

SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability

Xác định các lựa chọn để lọc khả năng định địa chỉ. Các giá trị mới có thể được thêm vào trong tương lai.

Enum
ADDRESSABILITY_UNSPECIFIED Khi không được chỉ định, dịch vụ sẽ chọn một giá trị mặc định hợp lý.
ANY Khả năng định địa chỉ không phải là tiêu chí lọc. Các đích đến được trả về bất kể khả năng định địa chỉ của chúng.
PRIMARY Tất cả đích đến được trả về sẽ có một địa điểm chính với địa chỉ hoặc tên đường.
WEAK Tất cả đích đến được trả về sẽ có một địa điểm chính hoặc một đích đến phụ có địa chỉ hoặc tên ở cấp đường.

Đích đến

Một điểm đến. Thông tin này bao gồm địa điểm chính, địa điểm liên quan, lối vào và điểm đi theo chỉ dẫn.

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)
    }
  ],
  "parkingOptions": {
    object (Destination.ParkingOptions)
  },
  "arrivalSummary": {
    object (Destination.ArrivalSummary)
  }
}
Trường
primary

object (PlaceView)

Địa điểm chính được xác định bằng primary_query trong yêu cầu.
containingPlaces[]

object (PlaceView)

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

object (PlaceView)

Điểm đến 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ụ 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 cho điểm đến này.
navigationPoints[]

object (NavigationPoint)

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

object (Destination.ParkingOptions)

Các lựa chọn đỗ xe cho điểm đến này.
arrivalSummary

object (Destination.ArrivalSummary)

Bản tóm tắt do AI tạo về trải nghiệm khi đến nơi.

PlaceView

Biểu thị một khung hiển thị của Địa điểm trong Places API. Đối tượng này cũng cung cấp thêm thông tin cụ thể về các đích đế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 thông tin mà API Địa điểm 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
  },
  "addressComponents": [
    {
      object (PlaceView.AddressComponent)
    }
  ]
}
Trường
place

string

Tên tài nguyên của Địa điểm này, ở định dạng places/{placeId}. Có thể dùng để tra cứu Địa điểm.
placeId

string

Giá trị nhận dạng riêng biệt của một địa điểm.
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 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ỉ 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 điểm 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, nên một đối tượng displayPolygon có thể biểu thị nhiều đa giác.
addressComponents[]

object (PlaceView.AddressComponent)

Các thành phần lặp lại cho từng cấp độ địa phương.

PlaceView.AddressComponent

Các thành phần có cấu trúc tạo nên địa chỉ được định dạng, nếu có thông tin này.

Biểu diễn dưới dạng JSON 
{
  "longText": string,
  "shortText": string,
  "types": [
    string
  ],
  "languageCode": string
}
Trường
longText

string

Nội dung mô tả hoặc tên đầy đủ của thành phần địa chỉ. Ví dụ: thành phần địa chỉ cho quốc gia Úc có thể có tên dài là "Úc".
shortText

string

Tên văn bản viết tắt cho thành phần địa chỉ (nếu có). Ví dụ: một thành phần địa chỉ cho quốc gia Úc có thể có tên ngắn là "AU".
types[]

string

Một mảng cho biết(các) loại thành phần địa chỉ.

Hãy xem https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types để biết thêm thông tin chi tiết.
languageCode

string

Ngôn ngữ dùng để định dạng thành phần này, theo ký hiệu CLDR.

Địa danh

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

Biểu diễn dưới dạng JSON 
{
  "relationalDescription": {
    object (LocalizedText)
  },
  "tags": [
    enum (Landmark.Tag)
  ],
  "straightLineDistanceMeters": number,
  "travelDistanceMeters": number,

  // 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
relationalDescription

object (LocalizedText)

Nội dung mô tả mà con người có thể đọc được về mối liên quan giữa đích đến và địa danh. Ví dụ: "Gần Toà nhà Empire State" hoặc "Đối diện Nhà Trắng".
tags[]

enum (Landmark.Tag)

Thẻ mô tả cách sử dụng địa danh trong bối cảnh của điểm đến.
straightLineDistanceMeters

number

Chỉ có đầu ra. Khoảng cách theo đường thẳng từ địa danh này đến đích đến (tính bằng mét).
travelDistanceMeters

number

Chỉ có đầu ra. Khoảng cách đi bộ từ địa danh này đến điểm đến (tính bằng mét).
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ể có mô tả cách sử dụng địa danh trong bối cảnh của một điểm đế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 điểm đến.

Enum
TAG_UNSPECIFIED Không được sử dụng.
ADDRESS Một địa điểm nổi bật tại địa phương có thể dùng để xác định vị trí khái quát của đích đến. Thường là trong vòng vài trăm mét tính từ điểm đến. Các địa danh này tương tự như địa danh được trả về bằng tính năng Thông tin mô tả địa chỉ của Geocoding API: https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors.
ARRIVAL Một địa điểm có thể giúp bạn đến được điểm đến. Hữu ích cho việc điều hướng khi bạn đến gần đích đến. Ví dụ: địa điểm này có thể là một nơi nằm ở phía bên kia đường so với điểm đến. Địa danh có thẻ này thường gần đích đến hơn so với địa danh 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,
  "streetViewThumbnail": {
    object (StreetViewThumbnail)
  },
  "streetViewAnnotation": {
    object (ImageAnnotation)
  }
}
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 thực sự nằm trên đó, ở định dạng places/{placeId}.
streetViewThumbnail

object (StreetViewThumbnail)

Hình thu nhỏ trong Chế độ xem đường phố cho thấy lối vào. Bạn có thể yêu cầu hình ảnh từ API Chế độ xem đường phố tĩnh. Hãy xem https://developers.google.com/maps/documentation/streetview/request-streetview.
streetViewAnnotation

object (ImageAnnotation)

Chú thích về lối vào trên streetViewThumbnail được trả về ở trên.

Entrance.Tag

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

Enum
TAG_UNSPECIFIED Không được sử dụng.
PREFERRED

Lối vào có thể là lối đi thực tế đến địa điểm chính trong điểm đế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 trung tâm mua sắm, thì lối vào "ƯU TIÊN" sẽ là lối vào có khả năng dẫn đến chính nhà hàng đó, còn các lối vào khác được trả về sẽ là các 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 trung tâm mua sắm.

Nếu địa điểm chính là một toà nhà, thì lối vào PREFERRED sẽ là 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, lối vào PREFERRED sẽ là lối vào cho phép đi vào khu vực sảnh chính, nhưng nếu một lối vào chỉ cho phép đ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 PREFERRED có thể không dẫn đến địa điểm chính và lối vào không phải PREFERRED có thể dẫn đến địa điểm chính.

StreetViewThumbnail

Các tham số để biểu thị hình thu nhỏ của Chế độ xem đường phố của Google. Bạn có thể sử dụng các tham số này để yêu cầu hình ảnh trong chế độ xem đường phố từ API tĩnh của Chế độ xem đường phố. Hãy xem tại https://developers.google.com/maps/documentation/streetview/request-streetview.

Biểu diễn dưới dạng JSON 
{
  "pano": string,
  "widthPx": integer,
  "heightPx": integer,
  "headingDegree": number,
  "pitchDegree": number,
  "fovDegree": number
}
Trường
pano

string

Mã nhận dạng ảnh toàn cảnh cụ thể.
widthPx

integer

Chiều rộng của hình thu nhỏ đầu ra, tính bằng pixel. Lưu ý: Khi yêu cầu chú thích cùng với hình thu nhỏ, bạn phải sử dụng các giá trị chiều cao và chiều rộng này trong yêu cầu API Chế độ xem đường phố để đảm bảo toạ độ chú thích khớp chính xác với hình ảnh.
heightPx

integer

Chiều cao của hình thu nhỏ đầu ra, tính bằng pixel. Lưu ý: Khi yêu cầu chú thích cùng với hình thu nhỏ, bạn phải sử dụng các giá trị chiều cao và chiều rộng này trong yêu cầu API Chế độ xem đường phố để đảm bảo rằng toạ độ chú thích căn chỉnh chính xác với hình ảnh.
headingDegree

number

Hướng ngang của camera tính bằng độ. Phạm vi [0, 360). 0 cho biết hướng Bắc và 90 cho biết hướng Đông.
pitchDegree

number

Hướng dọc của camera, tính bằng độ. Phạm vi [-90, 90]. 0 là đường chân trời, +90 là thẳng lên, -90 là thẳng xuống.
fovDegree

number

Trường nhìn ngang tính bằng độ. Phạm vi (0, 180]. Kiểm soát mức thu phóng. FOV càng nhỏ thì mức độ thu phóng càng lớn.

ImageAnnotation

Chú thích trên hình thu nhỏ của hình ảnh, chẳng hạn như một đa giác phác thảo lối vào.

Biểu diễn dưới dạng JSON 
{
  "coordinates": [
    {
      object (ImageAnnotation.Coordinate)
    }
  ]
}
Trường
coordinates[]

object (ImageAnnotation.Coordinate)

Danh sách toạ độ tạo thành một đa giác trên hình ảnh. Các toạ độ được sắp xếp ngược chiều kim đồng hồ.

ImageAnnotation.Coordinate

Toạ độ pixel của một điểm trên hình ảnh. Gốc toạ độ (0,0) là góc trên cùng bên trái của pixel trên cùng bên trái của hình ảnh, với trục x hướng sang phải và trục y hướng xuống dưới.

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

number

Toạ độ X.
yPx

number

Toạ độ Y.

Destination.ParkingOptions

Thông tin về các lựa chọn đỗ xe tại điểm đến.

Biểu diễn dưới dạng JSON 
{
  "availability": enum (Destination.ParkingOptions.Availability),
  "onsiteParking": boolean,
  "freeParkingLot": boolean,
  "paidParkingLot": boolean,
  "freeStreetParking": boolean,
  "paidStreetParking": boolean,
  "valetParking": boolean,
  "freeGarageParking": boolean,
  "paidGarageParking": boolean
}
Trường
availability

enum (Destination.ParkingOptions.Availability)

Tình trạng chỗ đỗ xe tại điểm đến này.
onsiteParking

boolean

Điểm đến có bãi đỗ xe tại chỗ.
freeParkingLot

boolean

Có bãi đỗ xe miễn phí.
paidParkingLot

boolean

Có bãi đỗ xe có tính phí.
freeStreetParking

boolean

Có chỗ đỗ xe miễn phí trên đường.
paidStreetParking

boolean

Có chỗ đỗ xe trên đường có tính phí.
valetParking

boolean

Có dịch vụ hỗ trợ đỗ xe.
freeGarageParking

boolean

Có gara đỗ xe miễn phí.
paidGarageParking

boolean

Có gara đỗ xe có tính phí.

Destination.ParkingOptions.Availability

Thước đo tổng hợp về mức độ khó khăn khi tìm chỗ đỗ xe khi đến địa điểm này.

Sau này, chúng tôi có thể thêm các giá trị mới.

Enum
AVAILABILITY_UNSPECIFIED Không có thông tin về tình trạng chỗ đỗ xe trống.
PLENTY Khách sạn có nhiều chỗ đỗ xe.
SOMEWHAT_DIFFICULT Hơi khó tìm chỗ đỗ xe.
DIFFICULT Rất khó tìm chỗ đỗ xe.

Destination.ArrivalSummary

Bản tóm tắt do AI tạo về trải nghiệm khi đến điểm đến.

Biểu diễn dưới dạng JSON 
{
  "text": {
    object (LocalizedText)
  },
  "flagContentUrl": string,
  "disclosureText": {
    object (LocalizedText)
  }
}
Trường
text

object (LocalizedText)

Tóm tắt về trải nghiệm khi đến điểm đến.
flagContentUrl

string

Đường liên kết để người dùng có thể gắn cờ báo cáo vấn đề về bản tóm tắt.
disclosureText

object (LocalizedText)

Chỉ có đầu ra. Chứa văn bản thông tin công bố cho thông tin tóm tắt về chuyến bay đến.