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。

一个上下文内容列表，其中每个条目都与 places 字段中相同索引处的相应地点相关联。优先考虑与请求中的 textQuery 相关的内容。如果某个地点的上下文相关内容不可用，则会返回非上下文相关内容。仅当相应地点没有内容时，此字段才会为空。如果请求了地点列表，此列表将包含与地点列表相同的条目数。
nextPageToken

string

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

string

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

授权范围

需要以下 OAuth 范围：

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

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)

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

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。

用户评价理由。此属性用于突出显示用户评价中最终用户感兴趣的部分。例如，如果搜索查询是“firewood pizza”，评价理由会突出显示与搜索查询相关的文本。

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

如果某个场所提供堂食服务。