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
}
字段
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 中包含的主要地点类型（例如“restaurant”或“gas_station”）。仅当此地方的主要类型包含在此列表中时，才会返回该地方。最多可以指定 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

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

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

boolean

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

string

可选。用于标识用于结算的自动补全会话的字符串。必须是网址和文件名安全 base64 字符串，长度最多为 36 个 ASCII 字符。否则，系统将返回 INVALID_ARGUMENT 错误。

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

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

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

响应正文

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，反之亦然。