自动补全（新）服务是一项可返回地点的网络服务 响应 HTTP 请求的响应和查询预测。在请求中指定一个文本 搜索字符串和地理边界，控制搜索区域。
自动补全（新）服务可以匹配完整字词和 来解析地点名称、地址和 plus 代码。因此，应用可以将 查询，以实时提供地点和查询预测。
Autocomplete（新）API 的响应可以包含两种类型 的预测：
- 地点预测：地点，例如商家、地址和 兴趣。地点预测 默认值。
- 查询预测：与输入文本字符串和
。默认情况下，查询预测不会返回。使用
includeQueryPredictions请求参数，用于将查询预测添加到 响应。
例如，您可以使用包含部分用户输入的字符串作为输入来调用 API， “Sicilian piz”（西西里岛），搜索区域仅限于加利福尼亚州旧金山。然后，响应中包含 与搜索字符串和搜索区域匹配的地点联想查询列表，例如 餐厅，并附上了这个地方的详细信息。
返回的地点预测旨在呈现给用户，以帮助 选择所需地点您可以 地点详情（新） 请求以获取有关返回的任何地点预测结果的更多信息。
响应还可以包含一系列与搜索查询相匹配的
搜索字符串和搜索区域，例如“西西里披萨和意大利面”。每个查询
响应包含 text 字段，该字段包含建议的文本搜索字符串。使用
作为输入
文本搜索（新）
执行更详细的搜索
利用 API Explorer，您可以发出实时请求，从而熟悉 API 和 API 选项：
试试看！“自动补全（新）”请求
“自动填充（新）”请求是对 表单：
https://places.googleapis.com/v1/places:autocomplete
将 JSON 请求正文或标头中的所有参数作为 POST 请求的一部分传递。 例如：
curl -X POST -d '{
"input": "pizza",
"locationBias": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
关于响应
Autocomplete（新）会返回一个 JSON 对象作为响应。 在响应中：
suggestions数组包含按顺序预测的所有地点和查询 根据其判断的相关性。每个地点都由placePrediction字段，每个查询都表示为 由queryPrediction字段指定。placePrediction字段包含单个 地点预测，包括地点 ID 和文本说明。queryPrediction字段包含单个 查询预测。
完整的 JSON 对象格式如下：
{
"suggestions": [
{
"placePrediction": {
"place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
"placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
"text": {
"text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
"matches": [
{
"endOffset": 6
}]
},
...
},
{
"queryPrediction": {
"text": {
"text": "Amoeba Music",
"matches": [
{
"endOffset": 6
}]
},
...
}
...]
}
必需参数
-
输入
要搜索的文本字符串。指定完整字词和子字符串， 地点名称、地址和 Plus Codes。 自动补全（新）服务 根据此字符串返回候选匹配项，并按照 感受到的相关性。
可选参数
-
includedPrimaryTypes
一个地点只能有一个主要类型 表 A 或 表 B.例如： 主要类型可能是
"mexican_restaurant"或"steak_house"。默认情况下，无论如何，该 API 都会根据
input参数返回所有地点。 。将结果限制为特定 primary type 或 primary 类型，请传递includedPrimaryTypes参数。使用此参数指定表 A 中最多五个类型值，或 表 B.地点必须 与要包含在响应中的某个指定主要类型值匹配。
不过，此参数还可能包含
(regions)或(cities)中的一个。(regions)类型的集合过滤器适用于区域或分区，例如社区和邮政编码。(cities)类型集合用于过滤 Google 已识别为城市的地点。如果出现以下情况，则请求将被拒绝并出现
INVALID_REQUEST错误：- 指定了超过五种类型。
- 除
(cities)或(regions)之外，还可以指定任何类型。 - 指定了所有无法识别的类型。
-
includeQueryPredictions
如果为
true，则响应同时包含地点和查询预测。默认 值为false，表示响应仅包含地点预测。 -
includedRegionCodes
仅包含来自指定区域列表的结果，该列表以最多 15 个数组的形式指定 ccTLD（“顶级域名”） 两个字符的值。如果省略，则不会对响应应用任何限制。例如： 将区域限制为德国和法国：
"includedRegionCodes": ["de", "fr"]如果您同时指定
locationRestriction和includedRegionCodes， 结果就会出现在两种设置的交集区域中。 -
inputOffset
从零开始的 Unicode 字符偏移量，表示
input中的光标位置。 光标位置会影响返回的预测结果。如果为空，则默认为 长度为input。 -
languageCode
返回结果时使用的首选语言。结果可能会以多种语言显示 如果
input中使用的语言不同于languageCode，或者返回的地点没有来自languageCode翻译为当地语言。- 您必须使用 IETF BCP-47 语言代码来指定首选语言。
-
如果未提供
languageCode，则 API 会使用Accept-Language标头。如果两者都未指定，则默认为en。如果您指定的语言代码无效，API 会返回INVALID_ARGUMENT个错误。 - 首选语言对要返回的结果集影响较小 API 选择返回的条目以及这些条目的返回顺序。 这也会影响 API 纠正拼写错误的能力。
-
API 尝试提供对用户和
同时反映用户的输入内容。地点预测
格式会有所不同，具体取决于每个请求中的用户输入。
-
首先选择
input参数中的匹配字词，并使用对齐的名称 以及languageCode参数指定的语言偏好设置， 否则使用最符合用户输入的名称。 -
街道地址采用本地语言的格式，以用户可阅读的脚本格式显示
选择匹配字词与
input参数。 -
完成匹配字词后，所有其他地址会以首选语言返回
与
input参数中的字词匹配。如果名称不是 ，则该 API 会使用最接近的匹配项。
-
首先选择
locationBias 或 locationRestriction
您可以指定
locationBias或locationRestriction， （但不能同时设置这两者）来定义搜索区域。将locationRestriction视为 结果所在的区域，以及locationBias指定结果必须靠近但可以不在的区域 数据。locationBias
指定要搜索的区域。这个位置就是一种偏差，这意味着 可返回指定位置周围的结果，包括结果 在指定区域之外。
locationRestriction
指定要搜索的区域。指定区域以外的搜索结果不予显示 返回。
将
locationBias或locationRestriction区域指定为 矩形视口或圆形圆形由中心点和半径（以米为单位）定义。半径必须在 0.0 和 50000.0（含边界值）。默认值为 0.0。对于
locationRestriction， 您必须将半径设置为大于 0.0 的值。否则，该请求会返回 没有匹配的结果。例如：
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }矩形是一种经纬度视口，表示为
low和高点对角线。视口被视为 表示它包含其边界。纬度边界 必须介于 -90 度（含）到 90 度（含）之间，且经度范围必须为 必须介于 -180 度到 180 度之间（包括 -180 度和 180 度）：- 如果
low=high，视口由该单点组成。 - 如果
low.longitude>high.longitude，经度范围会反转 （该视口与 180 度经度线相交）。 - 如果
low.longitude= -180 度，high.longitude= 180 度， 该视口包含所有经度。 - 如果
low.longitude= 180 度，high.longitude= -180 度， 经度范围为空。
low和high都必须填充，并且所表示的 box 不能为空。视口为空会导致错误。例如，以下视口将纽约市完全包围：
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }- 如果
-
源
要计算从该起点到终点的直线距离 目的地（返回为
distanceMeters）。如果此值 将不返回直线距离。必须指定为 经纬度坐标："origin": { "latitude": 40.477398, "longitude": -74.259087 } -
regionCode
用于设置响应格式的地区代码，指定为 ccTLD（“顶级域名”） 两个字符的值。大多数 ccTLD 代码都与 ISO 3166-1 代码相同， 但有一些值得注意的例外情况。例如，英国的 ccTLD 为 "uk"(.co.uk)，而其 ISO 3166-1 代码为“gb”（从技术层面来讲， “大不列颠及北爱尔兰联合王国”）。
如果您指定的地区代码无效，则 API 会返回
INVALID_ARGUMENT错误。根据适用法律，该参数可能会影响结果。 -
sessionToken
会话令牌是用户生成的字符串，用于跟踪自动补全情况 （新）调用作为“会话”。自动补全（新）会使用会话令牌 将用户自动补全搜索的查询和选择阶段归入单独的会话 结算目的。如需了解详情，请参阅 会话令牌。
自动补全（新）示例
使用 locationRestriction 和 locationBias
默认情况下，该 API 使用 IP 自定义调整来控制搜索区域。通过 IP 自定义调整，该 API 会使用
设备的 IP 地址，用于调整结果。您可以视需要使用
locationRestriction 或 locationBias（但不能同时使用这两者），以指定要搜索的区域。
locationRestriction 用于指定要搜索的区域。指定区域以外的结果
不会返回。在以下示例中，您将使用 locationRestriction 来限制
请求发送到以旧金山为中心、半径 5000 米的圆形：
curl -X POST -d '{
"input": "Amoeba",
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
指定区域内的所有结果都包含在 suggestions 数组中：
{
"suggestions": [
{
"placePrediction": {
"place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
"placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
"text": {
"text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
"matches": [
{
"endOffset": 6
}
]
},
"structuredFormat": {
"mainText": {
"text": "Amoeba Music",
"matches": [
{
"endOffset": 6
}
]
},
"secondaryText": {
"text": "Haight Street, San Francisco, CA, USA"
}
},
"types": [
"home_goods_store",
"establishment",
"store",
"point_of_interest",
"electronics_store"
]
}
}
]
}
使用 locationBias 时，位置会充当偏差，这意味着结果在
可返回指定位置，包括指定区域以外的结果。在未来
例如，您将请求更改为使用 locationBias：
curl -X POST -d '{
"input": "Amoeba",
"locationBias": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
结果现在包含更多项，包括半径 5000 米以外的结果：
{
"suggestions": [
{
"placePrediction": {
"place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
"placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
"text": {
"text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
"matches": [
{
"endOffset": 6
}
]
},
"structuredFormat": {
"mainText": {
"text": "Amoeba Music",
"matches": [
{
"endOffset": 6
}
]
},
"secondaryText": {
"text": "Haight Street, San Francisco, CA, USA"
}
},
"types": [
"electronics_store",
"point_of_interest",
"store",
"establishment",
"home_goods_store"
]
}
},
{
"placePrediction": {
"place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
"placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
"text": {
"text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
"matches": [
{
"endOffset": 6
}
]
},
"structuredFormat": {
"mainText": {
"text": "Amoeba Music",
"matches": [
{
"endOffset": 6
}
]
},
"secondaryText": {
"text": "Telegraph Avenue, Berkeley, CA, USA"
}
},
"types": [
"electronics_store",
"point_of_interest",
"establishment",
"home_goods_store",
"store"
]
}
},
...
]
}
使用 includePrimaryType
使用 includedPrimaryTypes 参数指定最多 5 个来自
表 A，
表 B，
或仅 (regions)，或仅 (cities)。地点必须与指定的
要包含在响应中的主要类型值。
在以下示例中，您指定了 input 字符串
“Soccer”并使用 includedPrimaryTypes 参数将结果限制为
"sporting_goods_store" 类型的场所：
curl -X POST -d '{
"input": "Soccer",
"includedPrimaryTypes": ["sporting_goods_store"],
"locationBias": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
如果您省略 includedPrimaryTypes 参数，则结果可能会包含
您不想要的类型，例如 "athletic_field"。
请求预测查询
默认情况下，查询预测不会返回。使用 includeQueryPredictions
请求参数，以将查询预测添加到响应中。例如：
curl -X POST -d '{
"input": "Amoeba",
"includeQueryPredictions": true,
"locationBias": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
suggestions 数组现在同时包含地点预测和查询预测
如上文关于响应部分所示。每个查询预测
包含 text 字段，该字段包含建议的文本搜索字符串。您可以
文本搜索（新）
请求获取有关所返回的任何联想查询的更多信息。
使用源
在此示例中，将 origin 作为纬度和经度坐标包含在请求中。
添加 origin 后，API 会在distanceMeters
响应，其中包含从 origin 到目的地的直线距离。
以下示例将原点设置为旧金山的中心：
curl -X POST -d '{
"input": "Amoeba",
"origin": {
"latitude": 37.7749,
"longitude": -122.4194
},
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
响应现在包含 distanceMeters：
{
"suggestions": [
{
"placePrediction": {
"place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
"placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
"text": {
"text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
"matches": [
{
"endOffset": 6
}
]
},
"structuredFormat": {
"mainText": {
"text": "Amoeba Music",
"matches": [
{
"endOffset": 6
}
]
},
"secondaryText": {
"text": "Haight Street, San Francisco, CA, USA"
}
},
"types": [
"home_goods_store",
"establishment",
"point_of_interest",
"store",
"electronics_store"
],
"distanceMeters": 3012
}
}
]
}
试试看！
借助 API Explorer，您可以发出示例请求， 您可以熟悉 API 和 API 选项。
- 选择 API 图标
，
。 - （可选）展开显示标准参数，并设置
fields参数 字段掩码。 - （可选）修改请求正文。
- 选择执行按钮。在弹出式窗口中，选择您要用于发出请求的账号。
在 API Explorer 面板中，选择“展开”图标，
用于展开 API Explorer 窗口。