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)

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

应仅设置 locationBiaslocationRestriction 中的一项。如果二者均未设置,则结果将因 IP 地址而有所偏差,也就是说,IP 地址将映射到不精确的位置,并用作偏差信号。

locationRestriction

object (LocationRestriction)

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

应仅设置 locationBiaslocationRestriction 中的一项。如果二者均未设置,则结果将因 IP 地址而有所偏差,也就是说,IP 地址将映射到不精确的位置,并用作偏差信号。

includedPrimaryTypes[]

string

可选。包含地点类型 (https://developers.google.com/maps/documentation/places/web-service/place-types) 中的主地点类型(例如“restaurant”或“gas_station”),或者仅包含 (regions),或者仅包含 (cities)。仅当地点的主要类型包含在此列表中时,系统才会返回该地点。最多可以指定 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

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

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

includeQueryPredictions

boolean

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

sessionToken

string

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

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

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

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

boolean

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

响应正文

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