自动补全(新)服务是一项可返回地点的网络服务 响应 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 窗口。