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)

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

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

locationRestriction

object (LocationRestriction)

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

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

includedPrimaryTypes[]

string

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

includedRegionCodes[]

string

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

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 不同。

如果请求 inputlanguageCode 采用不同语言,或者相应地方没有将本地语言翻译成 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,反之亦然。

如果请求 inputlanguageCode 采用不同语言,或者查询的部分内容没有从本地语言到 languageCode 的翻译,则可能为混合语言。

structuredFormat

object (StructuredFormat)

将查询预测细分为包含查询的主要文本和包含其他消除歧义特征(例如城市或区域)的辅助文本。

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