Method: places.searchText

Tìm kiếm địa điểm dựa trên cụm từ tìm kiếm bằ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 với 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 cho tìm kiếm bằ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, thì thông tin chi tiết về địa điểm bằng ngôn ngữ bất kỳ có thể được trả về, ưu tiên tiếng Anh nếu có thông tin chi tiết như vậy.

Danh sách các ngôn ngữ được hỗ trợ hiện tại: 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 được đưa ra. Tham số này được 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ó). Tham 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 phạm vi 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 (tính toàn bộ) với bước là 0,5, tức là [0, 0,5, 1,0, ..., 5,0] (tính toàn bộ). Điểm phân loại đầu vào sẽ được làm tròn lên đến 0,5 gần nhất(làm tròn lê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: Thay vào đó, hãy sử dụng pageSize.

Số lượng kết quả tối đa có thể trả về trên mỗi trang. Nếu số lượng kết quả có sẵn lớn hơn maxResultCount, thì nextPageToken sẽ được trả về. Bạn có thể truyền nextPageToken đến pageToken để nhận 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ị lớn hơn 20 sẽ được chuyển đổi thành 20. Các 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ố lượng kết quả tối đa có thể trả về trên mỗi trang. Nếu số lượng kết quả có sẵn lớn hơn pageSize, thì nextPageToken sẽ được trả về. Bạn có thể truyền nextPageToken đến pageToken để nhận 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. Các 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 thông tin này để truy xuất trang tiếp theo.

Khi phân trang, tất cả các tham số khác vớ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, lỗi INVALID_ARGUMENT sẽ được trả về.
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à có mức giá nhất định. Người dùng có thể chọn kết hợp các mức giá bất kỳ. Theo mặc định, tất cả các mức giá đều được chọn.
strictTypeFiltering

boolean

Dùng để đặt chế độ lọc theo loại nghiêm ngặt cho includedType. Nếu bạn đặt thành true, thì chỉ kết quả thuộc cùng một loại mới được trả về. 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à một thiên kiến, 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 hạn chế, tức là kết quả bên ngoài vị trí đã cho sẽ không được trả về. Không thể đặt cùng với locationBias.
evOptions

object (EVOptions)

Không bắt buộc. Đặt các lựa chọn có thể tìm kiếm về xe điện của một 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ác doanh nghiệp chỉ cung cấp dịch vụ tại cơ sở khách hàng nếu trường được đặt thành true. Doanh nghiệp chỉ cung cấp dịch vụ tại cơ sở khách hàng là 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ỉ 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. 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í cho những doanh nghiệp này.

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 những đị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 về việc định tuyến, 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 places. Nếu không có thông tin tóm tắt về đường đi cho một trong các địa điểm, thì thông tin đó sẽ chứa một mục trống. Danh sách này sẽ có số mục bằng với số địa điểm trong danh sách nếu được yêu cầu.
contextualContents[]

object (ContextualContent)

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

Một danh sách nội dung theo bối cảnh, trong đó mỗi mục liên kết với vị trí tương ứng trong cùng một chỉ mục trong trường places. Nội dung liên quan đến textQuery trong yêu cầu được ưu tiên. Nếu nội dung theo bối cảnh không có sẵn cho một trong các vị trí, thì nội dung không theo bối cảnh sẽ được trả về. Nội dung này sẽ chỉ trống khi nội dung không có sẵn cho địa điểm này. Danh sách này sẽ có số mục bằng với số địa điểm trong danh sách 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 cùng một cụm từ tìm kiếm dạng văn bản như được chỉ định trong yêu cầu trên Google Maps.

Phạm vi uỷ quyền

Yêu cầu phạm vi OAuth sau:

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

RankPreference

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

Enum
RANK_PREFERENCE_UNSPECIFIED Đối với một cụm từ tìm kiếm theo danh mục, chẳng hạn như "Nhà hàng ở Thành phố New York", MỨC ĐỘ PHÙ HỢP là tiêu chí mặc định. Đối với các cụm từ tìm kiếm không theo danh mục, chẳng hạn 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à một thiên kiến, 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 nhóm type.

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

object (Viewport)

Một hộp hình chữ nhật được xác định bằng góc đông bắc và tây nam. rectangle.high() phải là điểm ở phía đông bắc của khung nhìn hình chữ nhật. rectangle.low() phải là điểm ở phía 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(). Việc 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 hạn chế, tức là kết quả bên ngoài vị trí đã cho sẽ không đượ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)
  }
  // End of list of possible types for union field type.
}
Trường

Trường nhóm type.

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

object (Viewport)

Một hộp hình chữ nhật được xác định bằng góc đông bắc và tây nam. rectangle.high() phải là điểm ở phía đông bắc của khung nhìn hình chữ nhật. rectangle.low() phải là điểm ở phía 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(). Việc 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 cần thiết (tính bằng kilowatt). Những địa điểm có mức sạc thấp hơn mức được chỉ định sẽ bị lọc ra.
connectorTypes[]

enum (EVConnectorType)

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

SearchAlongRouteParameters

Chỉ định một đường nhiều đoạn được tính toán trước từ Routes API xác định tuyến đường cần tìm kiếm. Tìm kiếm dọc theo một tuyến đường tương tự như việc sử dụng lựa chọn yêu cầu locationBias hoặc locationRestriction để điều chỉnh kết quả tìm kiếm. Tuy nhiên, trong khi các lựa chọn locationBias và locationRestriction cho phép bạn chỉ định một khu vực để điều chỉnh kết quả tìm kiếm, thì lựa chọn này cho phép bạn điều chỉnh kết quả dọc theo một tuyến đường.

Kết quả không đảm bảo sẽ nằm dọc theo tuyến đường đã 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ỳ chọn là do 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 trên một tuyến đường thay thế, đặc biệt là nếu đường nhiều đoạn được cung cấp không xác định được tuyến đường tối ưu từ điểm khởi hành đế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. Đường nhiều đường của tuyến đường.

Hình nhiều đường

Một đường nhiều đường của tuyến đường. Chỉ hỗ trợ đường nhiều đoạn được mã hoá. Đường này có thể được truyền dưới dạng một chuỗi và bao gồm cả tính năng nén với mức độ hao hụt 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 nhóm polyline_type. Đóng gói loại đường nhiều đường. Đầu ra của Routes API mặc định là encoded_polyline. polyline_type chỉ có thể là một trong những trạng thái sau:
encodedPolyline

string

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

ContextualContent

Thử nghiệm: 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 theo ngữ cảnh đối với truy vấn về đị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, theo ngữ cảnh của 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, theo ngữ cảnh của cụm từ tìm kiếm về địa điểm.
justifications[]

object (Justification)

Thử nghiệm: 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: 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ý do giải đáp câu hỏi về lý do một địa điểm có thể thu hút người dùng cuối.

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 nhóm justification.

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

object (ReviewJustification)

Thử nghiệm: 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: 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: 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 đoạn trong bài đánh giá của người dùng mà người dùng cuối sẽ quan tâm. Ví dụ: nếu cụm từ tìm kiếm là "pizza củi", thì phần giải thích bài đánh giá sẽ làm nổi bật văn bản 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 ra.

HighlightedText

Văn bản được làm nổi bật bằng cách căn chỉnh. Đây là một phần của bài đánh giá. Từ chính xác cần đánh dấu đượ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 của văn bản được đánh dấu.

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

integer
endIndex

integer

BusinessAvailabilityAttributesJustification

Thử nghiệm: 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 của BusinessAvailabilityAttributes. Điều này cho thấy một số thuộc tính mà doanh nghiệp có thể thu hút người dùng cuối.

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

boolean

Nếu địa điểm có dịch vụ mang đi.
delivery

boolean

Nếu một địa điểm có dịch vụ giao hàng.
dineIn

boolean

Nếu một địa điểm có phục vụ dùng bữa tại chỗ.