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]（含 0 和 5.0）。输入评分将四舍五入为最接近的 0.5（上限）。例如，如果评分为 0.6，则会排除评分低于 1.0 的所有结果。
maxResultCount
(deprecated)

integer

已废弃：请改用 pageSize。

每页可返回的结果数上限。如果可用结果数大于 maxResultCount，则返回 nextPageToken，并将其传递给 pageToken，以在后续请求中获取下一页结果。如果提供 0 或未提供值，则使用默认值 20。最大值为 20；大于 20 的值将被强制转换为 20。负值将返回 INVALID_STRING 错误。

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

integer

可选。每页可返回的结果数上限。如果可用结果数大于 pageSize，则返回 nextPageToken，并将其传递给 pageToken，以在后续请求中获取下一页结果。如果提供 0 或未提供值，则使用默认值 20。最大值为 20；大于 20 的值将被设置为 20。负值将返回 INVALID_STRING 错误。

如果同时指定了 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。

上下文内容列表，其中每个条目都与 Places 字段中相同索引中的对应地点相关联。首选与请求中的 textQuery 相关的内容。如果某个地点无法提供相关上下文内容，则会返回非上下文内容。只有当相应地点没有相关内容时，此处才会显示内容。该列表中包含的条目数量应与地点列表的数量相同（如有请求）。
nextPageToken

string

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

RankPreference

结果在响应中如何排序。

枚举
RANK_PREFERENCE_UNSPECIFIED 对于分类查询（如“上海餐厅”），默认为“RELEVANCE”。对于非分类查询（例如“加利福尼亚州山景城”），我们建议您不要设置 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

某个地点是否提供堂食。