Method: places.autocomplete

返回给定输入的预测结果。

HTTP 请求

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

网址采用 gRPC 转码语法。

请求正文

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

JSON 表示法 
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string,
  "includePureServiceAreaBusinesses": boolean
}
字段
input

string

必需。要搜索的文本字符串。
locationBias

object (LocationBias)

可选。使结果偏向于指定位置。

最多只能设置 locationBias 和 locationRestriction 中的一个。如果两者都未设置，结果将根据 IP 地址自行调整，也就是说，IP 地址将被映射到不精确的位置，并用作自定义调整信号。
locationRestriction

object (LocationRestriction)

可选。将结果限制为指定位置。

最多只能设置 locationBias 或 locationRestriction 中的一项。如果二者均未设置，则结果将因 IP 地址而有所偏差，也就是说，IP 地址将映射到不精确的位置，并用作偏差信号。
includedPrimaryTypes[]

string

可选。在地点类型 (https://developers.google.com/maps/documentation/places/web-service/place-types) 中添加主要地点类型（例如“餐馆”或“gas_station”），或仅添加 (regions) 或仅 (cities)。只有当地点的主要类型包含在此列表中时，系统才会返回该地点。最多可以指定 5 个值。如果未指定任何类型，系统将返回所有地点类型。
includedRegionCodes[]

string

可选。仅包含指定地区的结果，最多可指定 15 个 CLDR 双字符地区代码。空集不会限制结果。如果同时设置了 locationRestriction 和 includedRegionCodes，结果将位于交叉路口区域。
languageCode

string

可选。返回结果时使用的语言。默认为 en-US。如果 input 中使用的语言与 languageCode 不同，或者返回的地点没有从本地语言翻译成 languageCode 的译文，则结果可能会混用多种语言。
regionCode

string

可选。地区代码，指定为 CLDR 双字符地区代码。这会影响地址格式、结果排名，并且可能会影响返回的结果。这不会将结果限制在指定区域内。如需将结果限制在某个区域，请使用 region_code_restriction。
origin

object (LatLng)

可选。用于计算到目的地的测地距离的起点（返回为 distanceMeters）。如果省略此值，将不会返回测地距离。
inputOffset

integer

可选。一个从零开始的 Unicode 字符偏移量 input，表示 input 中的光标位置。游标位置可能会影响返回的预测结果。

如果为空，则默认为 input 的长度。
includeQueryPredictions

boolean

可选。如果为 true，响应将同时包含地点和查询预测结果。否则，响应将仅返回地点预测结果。
sessionToken

string

可选。用于标识自动补全会话的字符串，以便进行结算。必须是网址和文件名安全的 base64 字符串，长度不得超过 36 个 ASCII 字符。否则，系统会返回 INVALID_ARGUMENT 错误。

会话在用户开始输入查询内容时开始，并在用户选择地点并执行对“地点详情”或“地址验证”的调用时结束。在每个会话中，用户可以输入多项查询内容，并最终发出一个地点详情或地址验证请求。在一个会话中，每个请求使用的凭据都必须属于同一 Google Cloud 控制台项目。会话结束后，令牌不再有效；您的应用必须为每个会话生成一个新的令牌。如果您省略 sessionToken 参数或重复使用会话令牌，系统会按未提供会话令牌的情况为会话计费（每个请求均单独结算）。

我们建议您遵循以下准则：

  • 针对所有地点自动补全调用使用会话令牌。
  • 为每个会话生成一个新的令牌。建议使用版本 4 UUID。
  • 确保为会话中的所有地点自动补全、地点详情和地址验证请求使用的凭据属于同一 Cloud 控制台项目。
  • 请务必为每个新会话传递唯一的会话令牌。对多个会话使用同一令牌会导致每个请求被单独计费。
includePureServiceAreaBusinesses

boolean

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

响应正文

places.autocomplete 的响应 proto。

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

JSON 表示法 
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
字段
suggestions[]

object (Suggestion)

包含建议列表，按相关性降序排序。

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)

由东北角和西南角定义的视口。
circle

object (Circle)

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

LocationRestriction

要搜索的区域。系统只会显示指定区域内的结果。

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)

由东北角和西南角定义的视口。
circle

object (Circle)

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

建议

自动补全建议结果。

JSON 表示法 
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
字段

联合字段 kind。

kind 只能是下列其中一项：
placePrediction

object (PlacePrediction)

对地点的预测。
queryPrediction

object (QueryPrediction)

对查询的预测。

PlacePrediction

地点自动补全预测的预测结果。

JSON 表示法 
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
字段
place

string

建议地点的资源名称。此名称可用于接受地点名称的其他 API。
placeId

string

建议地点的唯一标识符。此标识符可用于接受地点 ID 的其他 API。
text

object (FormattableText)

包含返回结果的可人工读取名称。对于相应地点的结果，这通常是指商家名称和地址。

对于希望显示单个界面元素的开发者，建议使用 text。如果开发者希望显示两个相互独立但相关的界面元素，可能需要改用 structuredFormat。它们是表示地点预测的两种不同方式。用户不应尝试将 structuredFormat 解析为 text，反之亦然。

此文本可能与 places.get 返回的 displayName 不同。

如果请求 input 和 languageCode 采用不同语言，或者相应地方没有将本地语言翻译成 languageCode，则可能采用混合语言。
structuredFormat

object (StructuredFormat)

将地点预测细分为主要文本（包含地点名称）和次要文本（包含其他用于消除歧义的地图项，例如城市或地区）。

建议希望显示两个单独但相关的界面元素的开发者使用 structuredFormat。如果开发者希望显示单个界面元素，则可能需要改用 text。它们是表示地点预测的两种不同方式。用户不应尝试将 structuredFormat 解析为 text，反之亦然。
types[]

string

https://developers.google.com/maps/documentation/places/web-service/place-types 中表格 A 或表格 B 中适用于此地点的类型列表。

类型是指地点的分类。具有相同类型的地点具有类似的特征。
distanceMeters

integer

测地线的长度（以米为单位），测地线起点为 origin（如果指定了 origin）。路线等某些联想查询可能不会填充此字段。

FormattableText

表示地点或查询预测的文本。您可以原封不动地使用此文本，也可以设置文本格式。

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

string

文本可以按原样使用，也可以使用 matches 设置格式。
matches[]

object (StringRange)

一个字符串范围列表，用于标识输入请求在 text 中的匹配位置。这些范围可用于设置 text 的特定部分的格式。如果匹配是根据字符串匹配以外的条件（例如拼写更正或转写）确定的，则子字符串可能与 input 不完全匹配。

这些值是 text 的 Unicode 字符偏移量。这些范围肯定会按照递增的偏移值进行排序。

StringRange

标识给定文本中的子字符串。

JSON 表示法 
{
  "startOffset": integer,
  "endOffset": integer
}
字段
startOffset

integer

字符串第一个 Unicode 字符（包括该字符）的从零开始的偏移量。
endOffset

integer

最后一个 Unicode 字符的从零开始的偏移量（不含）。

StructuredFormat

包含将地点或查询预测细分为主要文本和次要文本。

对于地点预测，主文本包含地点的具体名称。对于查询预测，主文本包含查询。

辅助文本包含其他用于消除歧义的地图项（例如城市或地区），以进一步识别地点或优化查询。

JSON 表示法 
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
字段
mainText

object (FormattableText)

表示地点或查询的名称。
secondaryText

object (FormattableText)

表示其他用于消除歧义的地图项（例如城市或地区），以进一步识别地点或优化查询。

QueryPrediction

查询自动补全预测的预测结果。

JSON 表示法 
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
字段
text

object (FormattableText)

预测的文本。此文本并不代表地点，而是可在搜索端点（例如文本搜索）中使用的文本查询。

对于希望显示单个界面元素的开发者，建议使用 text。如果开发者希望显示两个单独但相关的界面元素，则可能需要改用 structuredFormat。它们是表示查询预测的两种不同方式。用户不应尝试将 structuredFormat 解析为 text，反之亦然。

如果请求 input 和 languageCode 使用不同的语言，或者查询的部分内容没有从本地语言翻译成 languageCode，则可能混用多种语言。
structuredFormat

object (StructuredFormat)

将查询预测细分为包含查询的主要文本和包含其他歧义消除特征（例如城市或地区）的次要文本。

建议希望显示两个单独但相关的界面元素的开发者使用 structuredFormat。如果开发者希望显示单个界面元素，则可能需要改用 text。这两种是表示查询预测结果的两种不同方式。用户不应尝试将 structuredFormat 解析为 text，反之亦然。