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) 中或仅添加（地区）或仅添加表格 A 或表格 B 中的主要地点类型（例如“餐馆”或“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，反之亦然。