Method: places.searchText

Tìm kiếm địa điểm dựa trên cụm từ tìm kiếm dạng văn bản.

Yêu cầu HTTP

POST https://places.googleapis.com/v1/places:searchText

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 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "rankPreference": enum (RankPreference),
  "includedType": string,
  "openNow": boolean,
  "minRating": number,
  "maxResultCount": integer,
  "pageSize": integer,
  "pageToken": string,
  "priceLevels": [
    enum (PriceLevel)
  ],
  "strictTypeFiltering": boolean,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "evOptions": {
    object (EVOptions)
  },
  "routingParameters": {
    object (RoutingParameters)
  },
  "searchAlongRouteParameters": {
    object (SearchAlongRouteParameters)
  },
  "includePureServiceAreaBusinesses": boolean
}
Trường
textQuery

string

Bắt buộc. Cụm từ tìm kiếm dạng văn bản.
languageCode

string

Thông tin chi tiết về địa điểm sẽ hiển thị bằng ngôn ngữ ưu tiên (nếu có). Nếu mã ngôn ngữ không được chỉ định hoặc không được nhận dạng, hệ thống có thể trả về thông tin chi tiết về địa điểm bằng bất kỳ ngôn ngữ nào, ưu tiên tiếng Anh nếu có thông tin chi tiết như vậy.

Danh sách ngôn ngữ hiện được hỗ trợ: https://developers.google.com/maps/faq#languagesupport.
regionCode

string

Mã quốc gia/khu vực Unicode (CLDR) của vị trí nơi yêu cầu đến. Tham số này dùng để hiển thị thông tin chi tiết về địa điểm, chẳng hạn như tên địa điểm theo khu vực (nếu có). Thông số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.

Để biết thêm thông tin, hãy xem https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html.

Xin lưu ý rằng mã vùng gồm 3 chữ số hiện không được hỗ trợ.
rankPreference

enum (RankPreference)

Cách xếp hạng kết quả trong câu trả lời.
includedType

string

Loại địa điểm được yêu cầu. Danh sách đầy đủ các loại được hỗ trợ: https://developers.google.com/maps/documentation/places/web-service/place-types. Chỉ hỗ trợ một loại được đưa vào.
openNow

boolean

Dùng để giới hạn kết quả tìm kiếm ở những địa điểm hiện đang mở cửa. Giá trị mặc định là "false".
minRating

number

Lọc ra những kết quả có điểm xếp hạng trung bình của người dùng thấp hơn giới hạn này. Giá trị hợp lệ phải là số thực từ 0 đến 5 (bao gồm cả hai giá trị này) với tốc độ 0,5, tức là [0, 0,5, 1,0, ... , 5,0]. Mức phân loại đầu vào sẽ được làm tròn lên đến 0,5 gần nhất(giới hạn trên). Ví dụ: điểm xếp hạng 0,6 sẽ loại bỏ tất cả kết quả có điểm xếp hạng dưới 1,0.
maxResultCount
(deprecated)

integer

Không dùng nữa: Hãy sử dụng pageSize.

Số kết quả tối đa trên mỗi trang có thể được trả về. Nếu số lượng kết quả có sẵn lớn hơn maxResultCount, thì hệ thống sẽ trả về một nextPageToken có thể được truyền đến pageToken để lấy trang kết quả tiếp theo trong các yêu cầu tiếp theo. Nếu bạn cung cấp giá trị 0 hoặc không cung cấp giá trị nào, thì giá trị mặc định là 20 sẽ được sử dụng. Giá trị tối đa là 20; các giá trị trên 20 sẽ được chuyển đổi thành 20. Giá trị âm sẽ trả về lỗi INVALID_ARGUMENT.

Nếu bạn chỉ định cả maxResultCount và pageSize, thì maxResultCount sẽ bị bỏ qua.
pageSize

integer

Không bắt buộc. Số kết quả tối đa trên mỗi trang có thể được trả về. Nếu số lượng kết quả có sẵn lớn hơn pageSize, thì hệ thống sẽ trả về một nextPageToken có thể được truyền đến pageToken để lấy trang kết quả tiếp theo trong các yêu cầu tiếp theo. Nếu bạn cung cấp giá trị 0 hoặc không cung cấp giá trị nào, thì giá trị mặc định là 20 sẽ được sử dụng. Giá trị tối đa là 20; các giá trị trên 20 sẽ được đặt thành 20. Giá trị âm sẽ trả về lỗi INVALID_ARGUMENT.

Nếu bạn chỉ định cả maxResultCount và pageSize, thì maxResultCount sẽ bị bỏ qua.
pageToken

string

Không bắt buộc. Mã thông báo trang, nhận được từ lệnh gọi TextSearch trước đó. Cung cấp giá trị này để truy xuất trang tiếp theo.

Khi phân trang, tất cả các tham số khác ngoài pageToken, pageSize và maxResultCount được cung cấp cho TextSearch phải khớp với lệnh gọi ban đầu đã cung cấp mã thông báo trang. Nếu không, hệ thống sẽ trả về lỗi INVALID_ARGUMENT.
priceLevels[]

enum (PriceLevel)

Dùng để giới hạn phạm vi tìm kiếm ở những địa điểm được đánh dấu là ở một số mức giá nhất định. Người dùng có thể chọn bất kỳ tổ hợp cấp giá nào. Chọn tất cả các cấp giá theo mặc định.
strictTypeFiltering

boolean

Dùng để đặt tính năng lọc loại nghiêm ngặt cho includedType. Nếu bạn đặt giá trị này thành true, thì chỉ những kết quả thuộc cùng một loại mới được trả về. Giá trị mặc định là false.
locationBias

object (LocationBias)

Khu vực cần tìm kiếm. Vị trí này đóng vai trò là độ lệch, tức là kết quả xung quanh vị trí đã cho có thể được trả về. Không thể đặt cùng với locationRestriction.
locationRestriction

object (LocationRestriction)

Khu vực cần tìm kiếm. Vị trí này đóng vai trò là một quy tắc hạn chế, tức là hệ thống sẽ không trả về kết quả bên ngoài vị trí đã cho. Không thể đặt cùng với locationBias.
evOptions

object (EVOptions)

Không bắt buộc. Đặt các tuỳ chọn xe điện có thể tìm kiếm của yêu cầu tìm kiếm địa điểm.
routingParameters

object (RoutingParameters)

Không bắt buộc. Các tham số bổ sung để định tuyến đến kết quả.
searchAlongRouteParameters

object (SearchAlongRouteParameters)

Không bắt buộc. Proto tham số bổ sung để tìm kiếm dọc theo một tuyến đường.
includePureServiceAreaBusinesses

boolean

Không bắt buộc. Bao gồm cả những doanh nghiệp chỉ cung cấp dịch vụ tại cơ sở khách hàng nếu bạn đặt trường này thành true. Doanh nghiệp chỉ cung cấp dịch vụ tại cơ sở khách hàng là một doanh nghiệp trực tiếp cung cấp dịch vụ tận nơi hoặc giao hàng cho khách hàng, nhưng không phục vụ khách hàng tại địa chỉ của doanh nghiệp. Ví dụ: những doanh nghiệp cung cấp dịch vụ vệ sinh hoặc sửa ống nước. Những doanh nghiệp đó không có địa chỉ thực tế hoặc vị trí trên Google Maps. Đối với những doanh nghiệp này, Places sẽ không trả về các trường bao gồm location, plusCode và các trường khác liên quan đến vị trí.

Nội dung phản hồi

Giao thức phản hồi cho places.searchText.

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 
{
  "places": [
    {
      object (Place)
    }
  ],
  "routingSummaries": [
    {
      object (RoutingSummary)
    }
  ],
  "contextualContents": [
    {
      object (ContextualContent)
    }
  ],
  "nextPageToken": string,
  "searchUri": string
}
Trường
places[]

object (Place)

Danh sách địa điểm đáp ứng tiêu chí tìm kiếm bằng văn bản của người dùng.
routingSummaries[]

object (RoutingSummary)

Danh sách tóm tắt định tuyến, trong đó mỗi mục nhập liên kết đến vị trí tương ứng trong cùng một chỉ mục trong trường places. Nếu không có thông tin tóm tắt về tuyến đường cho một trong các địa điểm, thì thông tin tóm tắt đó sẽ chứa một mục trống. Danh sách này sẽ có nhiều mục nhập như danh sách địa điểm nếu được yêu cầu.
contextualContents[]

object (ContextualContent)

Thử nghiệm: Hãy xem https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative để biết thêm thông tin chi tiết.

Danh sách nội dung theo ngữ cảnh, trong đó mỗi mục liên kết với địa điểm tương ứng trong cùng một chỉ mục trong trường địa điểm. Nội dung liên quan đến textQuery trong yêu cầu được ưu tiên. Nếu không có nội dung theo bối cảnh cho một trong các địa điểm, thì hệ thống sẽ trả về nội dung không theo bối cảnh. Thẻ này sẽ chỉ trống khi không có nội dung nào cho địa điểm này. Danh sách này sẽ có nhiều mục nhập như danh sách địa điểm nếu được yêu cầu.
nextPageToken

string

Một mã thông báo có thể được gửi dưới dạng pageToken để truy xuất trang tiếp theo. Nếu bạn bỏ qua hoặc để trống trường này, thì sẽ không có trang tiếp theo.
searchUri

string

Đường liên kết cho phép người dùng tìm kiếm bằng chính cụm từ tìm kiếm dạng văn bản được chỉ định trong yêu cầu trên Google Maps.

RankPreference

Cách xếp hạng kết quả trong câu trả lời.

Enum
RANK_PREFERENCE_UNSPECIFIED Đối với cụm từ tìm kiếm theo danh mục như "Nhà hàng ở Thành phố New York", TÍNH LIÊN THỨC là giá trị mặc định. Đối với các cụm từ tìm kiếm không theo danh mục như "Mountain View, CA", bạn nên để rankPreference ở trạng thái chưa đặt.
DISTANCE Xếp hạng kết quả theo khoảng cách.
RELEVANCE Xếp hạng kết quả theo mức độ liên quan. Thứ tự sắp xếp do ngăn xếp xếp hạng thông thường xác định.

LocationBias

Khu vực cần tìm kiếm. Vị trí này đóng vai trò là độ lệch, tức là kết quả xung quanh vị trí đã cho có thể được trả về.

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

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
Trường

Trường hợp hợp nhất type.

type chỉ có thể là một trong những giá trị sau:
rectangle

object (Viewport)

Hộp hình chữ nhật được xác định bởi góc đông bắc và tây nam. rectangle.high() phải là điểm đông bắc của khung nhìn hình chữ nhật. rectangle.low() phải là điểm tây nam của khung nhìn hình chữ nhật. rectangle.low().latitude() không được lớn hơn rectangle.high().latitude(). Điều này sẽ dẫn đến một dải vĩ độ trống. Khung nhìn hình chữ nhật không được rộng hơn 180 độ.
circle

object (Circle)

Một hình tròn được xác định bằng tâm điểm và bán kính.

LocationRestriction

Khu vực cần tìm kiếm. Vị trí này đóng vai trò là một quy tắc hạn chế, tức là hệ thống sẽ không trả về kết quả bên ngoài vị trí đã cho.

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

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Trường

Trường hợp hợp nhất type.

type chỉ có thể là một trong những giá trị sau:
rectangle

object (Viewport)

Hộp hình chữ nhật được xác định bởi góc đông bắc và tây nam. rectangle.high() phải là điểm đông bắc của khung nhìn hình chữ nhật. rectangle.low() phải là điểm tây nam của khung nhìn hình chữ nhật. rectangle.low().latitude() không được lớn hơn rectangle.high().latitude(). Điều này sẽ dẫn đến một dải vĩ độ trống. Khung nhìn hình chữ nhật không được rộng hơn 180 độ.

EVOptions

Các lựa chọn về xe điện có thể tìm kiếm của một yêu cầu tìm kiếm địa điểm.

Biểu diễn dưới dạng JSON 
{
  "minimumChargingRateKw": number,
  "connectorTypes": [
    enum (EVConnectorType)
  ]
}
Trường
minimumChargingRateKw

number

Không bắt buộc. Tốc độ sạc tối thiểu bắt buộc tính bằng kilowatt. Những địa điểm có mức giá sạc thấp hơn mức giá đã chỉ định sẽ bị lọc ra.
connectorTypes[]

enum (EVConnectorType)

Không bắt buộc. Danh sách các loại đầu nối xe điện ưu tiên. Những địa điểm không hỗ trợ bất kỳ loại đầu nối nào trong danh sách sẽ bị lọc ra.

SearchAlongRouteParameters

Chỉ định một đa tuyến tính toán trước từ Routes API (API Tuyến đường) xác định tuyến đường cần tìm kiếm. Tìm kiếm dọc theo một tuyến đường cũng tương tự như sử dụng tuỳ chọn yêu cầu locationBias hoặc locationRestriction để thiên vị kết quả tìm kiếm. Tuy nhiên, mặc dù các tuỳ chọn locationBias và locationRestriction cho phép bạn chỉ định một khu vực để thiên vị kết quả tìm kiếm, nhưng tuỳ chọn này cho phép bạn thiên vị kết quả dọc theo tuyến đường đi.

Kết quả không được đảm bảo sẽ nằm dọc theo tuyến đường được cung cấp, mà được xếp hạng trong khu vực tìm kiếm do đường đa tuyến xác định và tuỳ ý theo locationBias hoặc locationRestriction dựa trên thời gian đi đường vòng tối thiểu từ điểm xuất phát đến điểm đến. Kết quả có thể nằm dọc theo một tuyến đường thay thế, đặc biệt là nếu đường đa tuyến được cung cấp không xác định tuyến đường tối ưu từ điểm xuất phát đến điểm đến.

Biểu diễn dưới dạng JSON 
{
  "polyline": {
    object (Polyline)
  }
}
Trường
polyline

object (Polyline)

Bắt buộc. Hình nhiều đường của tuyến đường.

Hình nhiều đường

Hình nhiều đường của tuyến đường. Chỉ hỗ trợ đường đa tuyến được mã hoá, có thể được truyền dưới dạng chuỗi và bao gồm cả tính năng nén với mức độ hao tổn tối thiểu. Đây là đầu ra mặc định của Routes API.

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

  // Union field polyline_type can be only one of the following:
  "encodedPolyline": string
  // End of list of possible types for union field polyline_type.
}
Trường
Trường hợp hợp nhất polyline_type. Đóng gói loại đường đa tuyến. Đầu ra API tuyến đường mặc định là encoded_polyline. polyline_type chỉ có thể là một trong những giá trị sau:
encodedPolyline

string

Một đường đa tuyến được mã hoá, do Routes API trả về theo mặc định. Xem các công cụ mã hoá và giải mã.

ContextualContent

Thử nghiệm: Hãy xem https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative để biết thêm thông tin chi tiết.

Nội dung phù hợp với ngữ cảnh của cụm từ tìm kiếm địa điểm.

Biểu diễn dưới dạng JSON 
{
  "reviews": [
    {
      object (Review)
    }
  ],
  "photos": [
    {
      object (Photo)
    }
  ],
  "justifications": [
    {
      object (Justification)
    }
  ]
}
Trường
reviews[]

object (Review)

Danh sách bài đánh giá về địa điểm này, phù hợp với cụm từ tìm kiếm về địa điểm.
photos[]

object (Photo)

Thông tin (bao gồm cả thông tin tham khảo) về ảnh của địa điểm này, phù hợp với cụm từ tìm kiếm địa điểm.
justifications[]

object (Justification)

Thử nghiệm: Hãy xem https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative để biết thêm thông tin chi tiết.

Lý do cho địa điểm đó.

Lý giải

Thử nghiệm: Hãy xem https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative để biết thêm thông tin chi tiết.

Lý do cho địa điểm đó. Nội dung giải thích trả lời câu hỏi tại sao một địa điểm có thể khiến người dùng cuối quan tâm.

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

  // Union field justification can be only one of the following:
  "reviewJustification": {
    object (ReviewJustification)
  },
  "businessAvailabilityAttributesJustification": {
    object (BusinessAvailabilityAttributesJustification)
  }
  // End of list of possible types for union field justification.
}
Trường

Trường hợp hợp nhất justification.

justification chỉ có thể là một trong những giá trị sau:
reviewJustification

object (ReviewJustification)

Thử nghiệm: Hãy xem https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative để biết thêm thông tin chi tiết.
businessAvailabilityAttributesJustification

object (BusinessAvailabilityAttributesJustification)

Thử nghiệm: Hãy xem https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative để biết thêm thông tin chi tiết.

ReviewJustification

Thử nghiệm: Hãy xem https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative để biết thêm thông tin chi tiết.

Lý do cho bài đánh giá của người dùng. Phần này làm nổi bật một phần của bài đánh giá mà người dùng cuối sẽ quan tâm. Ví dụ: nếu cụm từ tìm kiếm là "pizza nướng bằng củi", thì nội dung giải thích về bài đánh giá sẽ làm nổi bật văn bản có liên quan đến cụm từ tìm kiếm đó.

Biểu diễn dưới dạng JSON 
{
  "highlightedText": {
    object (HighlightedText)
  },
  "review": {
    object (Review)
  }
}
Trường
highlightedText

object (HighlightedText)
review

object (Review)

Bài đánh giá mà văn bản được đánh dấu được tạo từ đó.

HighlightedText

Văn bản được làm nổi bật bằng căn chỉnh. Đây là một phần của chính bài đánh giá đó. Từ chính xác cần làm nổi bật được đánh dấu bằng HighlightedTextRange. Có thể có một số từ trong văn bản được làm nổi bật.

Biểu diễn dưới dạng JSON 
{
  "text": string,
  "highlightedTextRanges": [
    {
      object (HighlightedTextRange)
    }
  ]
}
Trường
text

string
highlightedTextRanges[]

object (HighlightedTextRange)

Danh sách các dải ô của văn bản được đánh dấu.

HighlightedTextRange

Phạm vi văn bản được làm nổi bật.

Biểu diễn dưới dạng JSON 
{
  "startIndex": integer,
  "endIndex": integer
}
Trường
startIndex

integer
endIndex

integer

BusinessAvailabilityAttributesJustification

Thử nghiệm: Hãy xem https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative để biết thêm thông tin chi tiết. Lý do cho việc sử dụng BusinessAvailabilityAttributes. Đây là một số thuộc tính mà doanh nghiệp có thể cung cấp và có thể khiến người dùng cuối quan tâm.

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

boolean

Liệu địa điểm đó có phục vụ đồ ăn mang đi không.
delivery

boolean

Liệu địa điểm đó có cung cấp dịch vụ giao hàng tận nơi hay không.
dineIn

boolean

Liệu địa điểm đó có phục vụ ăn uống tại chỗ hay không.