Method: places.searchText

基于文本查询的地点搜索。

HTTP 请求

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

网址采用 gRPC 转码语法。

请求正文

请求正文中包含结构如下的数据：

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)
  }
}
字段
textQuery

string

必需。用于文本搜索的文本查询。
languageCode

string

系统将以首选语言（如果有）显示地点详情。如果未指定或无法识别语言代码，系统可能会返回任意语言的地点详情，如果存在此类详情，会优先返回英语。

当前支持的语言列表：https://developers.google.com/maps/faq#languagesupport。
regionCode

string

请求来源位置的 Unicode 国家/地区代码 (CLDR)。此参数用于显示地点详情，例如特定于地区的地点名称（如果有）。根据适用法律，该参数可能会影响结果。

如需了解详情，请参阅 https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html。

请注意，目前不支持 3 位数的区域代码。
rankPreference

enum (RankPreference)

结果在响应中如何排名。
includedType

string

所请求的地点类型。支持的类型的完整列表：https://developers.google.com/maps/documentation/places/web-service/place-types。仅支持一种包含的类型。
openNow

boolean

用于将搜索范围限制为当前营业的地点。默认值为 false。
minRating

number

滤除平均用户评分严格低于此限制的结果。有效值必须是介于 0 和 5（含）之间的浮点数，频率必须为 0.5，即 [0, 0.5, 1.0, ... , 5.0]（包括 1 和 5.0]）。输入的分级会四舍五入到最接近的 0.5（上限）。例如，评分为 0.6 将排除评分低于 1.0 的所有结果。
maxResultCount
(deprecated)

integer

已弃用：请改用 pageSize。

每页可返回的结果数上限。如果可用结果数超过 maxResultCount，则返回 nextPageToken，您可以将其传递给 pageToken，以在后续请求中获取下一页结果。如果为 0 或未提供任何值，则使用默认值 20。最大值为 20；高于 20 的值将被强制转换为 20。若将此值设为负值，则会返回“INVALID_ARGUMENT”错误。

如果同时指定了 maxResultCount 和 pageSize，则系统将忽略 maxResultCount。
pageSize

integer

可选。每页可返回的结果数上限。如果可用结果数超过 pageSize，则返回 nextPageToken，您可以将其传递给 pageToken，以在后续请求中获取下一页结果。如果为 0 或未提供任何值，则使用默认值 20。最大值为 20；高于 20 的值将被设为 20。若将此值设为负值，则会返回“INVALID_ARGUMENT”错误。

如果同时指定了 maxResultCount 和 pageSize，则系统将忽略 maxResultCount。
pageToken

string

可选。从上一次 TextSearch 调用收到的页面令牌。利用其进行后续页面检索。

分页时，提供给 TextSearch 的 pageToken、pageSize 和 maxResultCount 以外的所有参数都必须与提供页面令牌的初始调用匹配。否则，系统会返回 INVALID_ARGUMENT 错误。
priceLevels[]

enum (PriceLevel)

用于将搜索范围限制为标记为特定价位的地点。用户可以选择任意价位组合。默认选择所有价位。
strictTypeFiltering

boolean

用于为 includeType 设置严格的类型过滤。如果设置为 true，则仅返回相同类型的结果。默认值为 false。
locationBias

object (LocationBias)

要搜索的地区。此位置可充当偏差，这意味着可能会返回指定位置附近的结果。不能与 locationRestriction 一起设置。
locationRestriction

object (LocationRestriction)

要搜索的地区。此位置起到了限制作用，这意味着将不会返回指定位置以外的结果。不能与 locationBias 一起设置。
evOptions

object (EVOptions)

可选。设置地点搜索请求的可搜索电动汽车选项。

响应正文

places.searchText 的响应 proto。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "places": [
    {
      object (Place)
    }
  ],
  "contextualContents": [
    {
      object (ContextualContent)
    }
  ],
  "nextPageToken": string
}
字段
places[]

object (Place)

满足用户文本搜索条件的地点列表。
contextualContents[]

object (ContextualContent)

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。

上下文内容列表，其中每个条目都与地点字段中相同索引的相应地点相关联。首选与请求中的 textQuery 相关的内容。如果其中某个地点无法获取背景信息，则该地点将返回非上下文内容。仅当此内容不适用于此地点时，此字段才为空。如果请求的话，此列表中包含的条目数应该与地点列表数量一样多。
nextPageToken

string

可作为 pageToken 发送以检索下一页的令牌。如果此字段省略或为空，则不存在后续页面。

RankPreference

结果在响应中如何排名。

枚举
RANK_PREFERENCE_UNSPECIFIED 对于分类查询（例如“纽约市的餐馆”），RELEVANCE 是默认值。对于非分类查询，例如“Mountain View, CA”我们建议您不要设置 rankPreference。
DISTANCE 按距离对结果进行排名。
RELEVANCE 按相关性对结果进行排名。由常规排名堆栈确定的排序顺序。

LocationBias

要搜索的地区。此位置可充当偏差，这意味着可能会返回指定位置附近的结果。

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.
}
字段

联合字段 type。

type 只能是下列其中一项：
rectangle

object (Viewport)

由东北角和西南角定义的矩形框。rectangle.high() 必须是矩形视口的东北点。rectangle.low() 必须是矩形视口的西南点。rectangle.low().latitude()不能大于 rectangle.high().latitude()。这会导致纬度范围为空。矩形视口的宽度不能超过 180 度。
circle

object (Circle)

由中心点和半径定义的圆形。

LocationRestriction

要搜索的地区。此位置起到了限制作用，这意味着将不会返回指定位置以外的结果。

JSON 表示法 
{

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

联合字段 type。

type 只能是下列其中一项：
rectangle

object (Viewport)

由东北角和西南角定义的矩形框。rectangle.high() 必须是矩形视口的东北点。rectangle.low() 必须是矩形视口的西南点。rectangle.low().latitude()不能大于 rectangle.high().latitude()。这会导致纬度范围为空。矩形视口的宽度不能超过 180 度。

EVOptions

地点搜索请求的可搜索电动汽车选项。

JSON 表示法 
{
  "minimumChargingRateKw": number,
  "connectorTypes": [
    enum (EVConnectorType)
  ]
}
字段
minimumChargingRateKw

number

可选。所需的最低充电速率（以千瓦为单位）。充电费率低于指定费率的地点会被滤除。
connectorTypes[]

enum (EVConnectorType)

可选。首选的电动汽车连接器类型列表。不支持任何所列连接器类型的位置会被滤除。

ContextualContent

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。

与地点查询相关的上下文内容。

JSON 表示法 
{
  "reviews": [
    {
      object (Review)
    }
  ],
  "photos": [
    {
      object (Photo)
    }
  ],
  "justifications": [
    {
      object (Justification)
    }
  ]
}
字段
reviews[]

object (Review)

关于此地点的评价列表，与地点查询相关。
photos[]

object (Photo)

与地点查询相关的此地点照片的相关信息（包括引用）。
justifications[]

object (Justification)

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。

该地点的理由。

理由

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。

该地点的理由。“理由”功能旨在解释最终用户为何会对某个地点产生兴趣这一问题。

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.
}
字段

联合字段 justification。

justification 只能是下列其中一项：
reviewJustification

object (ReviewJustification)

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。
businessAvailabilityAttributesJustification

object (BusinessAvailabilityAttributesJustification)

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。

ReviewJustification

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。

用户评价的理由。这会突出显示最终用户可能感兴趣的用户评价部分。例如，如果搜索查询为“柴火披萨”，评价理由会突出显示与搜索查询相关的文字。

JSON 表示法 
{
  "highlightedText": {
    object (HighlightedText)
  },
  "review": {
    object (Review)
  }
}
字段
highlightedText

object (HighlightedText)
review

object (Review)

生成突出显示的文字所依据的评价。

HighlightedText

通过理由突出显示的文本。这是该评价的一部分。要突出显示的确切字词由 HighlightedTextRange 标记。突出显示的文本中可能有多个字词。

JSON 表示法 
{
  "text": string,
  "highlightedTextRanges": [
    {
      object (HighlightedTextRange)
    }
  ]
}
字段
text

string
highlightedTextRanges[]

object (HighlightedTextRange)

突出显示的文本范围的列表。

HighlightedTextRange

突出显示的文本的范围。

JSON 表示法 
{
  "startIndex": integer,
  "endIndex": integer
}
字段
startIndex

integer
endIndex

integer

BusinessAvailabilityAttributesJustification

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative。BusinessAvailabilityAttributes 的理由。此列显示商家可能对最终用户感兴趣的一些属性。

JSON 表示法 
{
  "takeout": boolean,
  "delivery": boolean,
  "dineIn": boolean
}
字段
takeout

boolean

某个地点是否提供外卖服务。
delivery

boolean

相应地点是否提供送餐服务。
dineIn

boolean

某个地点是否提供堂食。