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)
  },
  "routingParameters": {
    object (RoutingParameters)
  },
  "searchAlongRouteParameters": {
    object (SearchAlongRouteParameters)
  },
  "includePureServiceAreaBusinesses": boolean
}
字段
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.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

用于为 includedType 设置严格的类型过滤。如果设为 true，则只会返回同一类型的结果。默认值为 false。
locationBias

object (LocationBias)

要搜索的区域。此位置用作偏差，这意味着系统可能会返回给定位置周围的结果。不能与 locationRestriction 一起设置。
locationRestriction

object (LocationRestriction)

要搜索的区域。此位置作为限制条件，这意味着系统不会返回给定位置以外的结果。不能与 locationBias 一起设置。
evOptions

object (EVOptions)

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

object (RoutingParameters)

可选。用于路由到结果的其他参数。
searchAlongRouteParameters

object (SearchAlongRouteParameters)

可选。用于沿路线搜索的其他参数 proto。
includePureServiceAreaBusinesses

boolean

可选。如果此字段设为 true，则包含纯上门服务商家。纯上门服务商家是指为客户送货上门或提供上门服务，但不在自己的商家地址为客户提供服务的商家。例如，清洁服务类商家或管道工。这些商家在 Google 地图上没有实际地址或营业地点。地点不会为这些商家返回 location、plusCode 和其他与位置相关的字段。

响应正文

places.searchText 的响应 proto。

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

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

object (Place)

符合用户文本搜索条件的地点列表。
routingSummaries[]

object (RoutingSummary)

路线摘要列表，其中每个条目都与 places 字段中相同索引中的相应地点相关联。如果某个地点没有路线摘要，则路线摘要中会包含一个空条目。此列表中包含的条目数量与地点列表数量一样多（如果请求的话）。
contextualContents[]

object (ContextualContent)

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

情境内容列表，其中每个条目都与“地点”字段中同一索引中的相应地点相关联。首选与请求中的 textQuery 相关的内容。如果某个地点没有上下文相关内容，则会返回非上下文相关内容。只有当此地点没有相应内容时，此字段才会为空。如果请求，此列表中的条目数量将与地点列表中的条目数量相同。
nextPageToken

string

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

string

用户可以通过该链接在 Google 地图上使用请求中指定的相同文本查询进行搜索。

RankPreference

结果在响应中的排名方式。

枚举
RANK_PREFERENCE_UNSPECIFIED 对于分类查询（例如“纽约市餐厅”），默认是“相关性”。对于非分类查询（例如“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)

可选。首选电动汽车连接器类型的列表。系统会滤除不支持所列任何连接器类型的地点。

SearchAlongRouteParameters

指定 Routes API 中预计算的多段线，用于定义要搜索的路线。沿路线搜索类似于使用 locationBias 或 locationRestriction 请求选项来偏向搜索结果。不过，虽然 locationBias 和 locationRestriction 选项可让您指定一个区域来自定义调整搜索结果，但此选项可让您自定义行程路线的结果。

结果未必沿着所提供的路线，而是会根据多段线所定义的搜索区域（以及可选的 locationBias 或 locationRestriction）内从起点到目的地的最短绕道时间进行排名。结果可能沿着备选路线，尤其是在所提供的多段线未定义从起点到目的地的最佳路线时。

JSON 表示法 
{
  "polyline": {
    object (Polyline)
  }
}
字段
polyline

object (Polyline)

必需。路线多段线。

折线

路线多段线。仅支持编码多段线，该多段线可作为字符串传递，且包含损失最低的压缩。这是 Routes API 的默认输出。

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.
}
字段
联合字段 polyline_type。封装折线的类型。Routes API 输出默认为 encoded_polyline。polyline_type 只能是下列其中一项：
encodedPolyline

string

编码多段线，默认由 Routes API 返回。请参阅编码器和解码器工具。

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

相应地点是否提供堂食。