自动补全(新)会在以下位置返回地点预测: 对包含文本搜索字符串和地理边界的请求的响应 用于控制搜索区域的控件。自动补全可以匹配 对输入的完整字词和子字符串进行解析,从而解析地点名称、地址和 plus 代码。您的应用可以发送查询 以实时提供地点和查询预测。
例如,您可以调用 Autocomplete,使用 包含部分用户输入“Sicilian piz”以及搜索区域的字符串 仅限加利福尼亚州旧金山。然后,响应中包含地点列表 与搜索字符串和搜索区域匹配的联想查询(如餐馆) 名为“西西里披萨厨房”
返回的地点预测结果旨在呈现给用户,以帮助 选择所需地点您可以创建地点详情 (新)请求以获取更多 返回的任何地点预测的相关信息。
“自动补全(新)”请求
您的应用可以获得预测地点名称和/或
从 Autocomplete API 检索新地址。
PlacesClient.findAutocompletePredictions()
、
通过一个
FindAutocompletePredictionsRequest
对象。以下示例显示了对
PlacesClient.findAutocompletePredictions()
。
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Sicilian piz") .setRegionCode("ES") .setLocationRestriction(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
自动补全(新)响应
该 API 会返回一个
FindAutocompletePredictionsResponse
以
Task
。
通过
FindAutocompletePredictionsResponse
包含最多五个
AutocompletePrediction
对象来表示预测的地点。如果没有
与查询和过滤条件对应的已知位置。
对于每个预测地点,您都可以调用以下方法来检索地点 详细信息:
getFullText(CharacterStyle)
用于返回地点说明的完整文本。这是由 主要文本和辅助文本示例:“Eiffel Tower, Avenue Anatole France, Paris, France”。此外,您还可以通过此方法突出显示 与搜索内容相符的说明,并使用CharacterStyle
。CharacterStyle
参数是可选的。如果不需要,请将其设置为 null 任何突出显示的内容。getPrimaryText(CharacterStyle)
用于返回描述地点的主要文本。这通常是 位置。示例:“Eiffel Tower”和“123 Pitt Street”。getSecondaryText(CharacterStyle)
返回地点说明的附属文本。对于 。示例: “Avenue Anatole France, Paris, France”和“Sydney, New South Wales”。getPlaceId()
返回预测地点的地点 ID。地点 ID 是一个文本 唯一标识地点的标识符,可用于检索Place
对象。如需详细了解地点 ID,请参阅 自动补全,请参阅地点详情 (新)。普通 有关地点 ID 的信息,请参阅地点 ID 概览。getTypes()
用于返回与此地点相关联的地点类型的列表。getDistanceMeters()
用于返回此地点与 指定来源。
必需参数
-
查询
要搜索的文本字符串。指定完整字词和子字符串, 地点名称、地址和 Plus Codes。 自动补全(新)服务 根据此字符串返回候选匹配项,并按照 感受到的相关性。
如需设置查询参数,请调用
setQuery()
方法。FindAutocompletePredictionsRequest
可选参数
-
主要类型
从类型中选择最多五个类型值的列表 表 A 或表 B 用于过滤响应中返回的地点。 地点必须与某个指定的主要类型值匹配,才能包含在响应中。
一个地点只能有一个主要类型 表 A 或表 B 关联的 。例如,主要类型可能是
"mexican_restaurant"
或"steak_house"
。如果出现以下情况,则请求将被拒绝并出现
INVALID_REQUEST
错误:- 指定了超过五种类型。
- 指定了所有无法识别的类型。
如需设置主要类型参数,请调用
setTypesFilter()
方法。FindAutocompletePredictionsRequest
-
国家/地区
仅包含来自指定国家/地区列表的结果,这些国家/地区列表最多指定为 15 个 ccTLD(“顶级域名”) 两个字符的值。如果省略,则不会对响应应用任何限制。例如: 将区域限制为德国和法国:
如果您同时指定
locationRestriction
和includedRegionCodes
, 结果就会出现在两种设置的交集区域中。如需设置“国家/地区”参数,请调用
setCountries()
方法。FindAutocompletePredictionsRequest
-
输入偏移
从零开始的 Unicode 字符偏移量,表示查询中的光标位置。 光标位置会影响返回的预测结果。如果为空,则默认为 查询的长度。
如需设置输入偏移参数,请调用
setInputOffset()
方法。FindAutocompletePredictionsRequest
位置偏向或位置限制
您可以指定位置偏向或位置限制 (但不能同时设置这两者)来定义搜索区域。可以将位置限制视为 结果所在的区域,以及位置偏差, 用于指定结果必须靠近的区域。主要区别在于 存在位置偏向,则系统可能仍会返回指定区域以外的结果。
位置偏向
指定要搜索的区域。这个位置只是一种偏见,而不是限制,因此 但指定区域以外的地方仍可以返回。
如需设置位置自定义调整参数,请调用
setLocationBias()
方法。FindAutocompletePredictionsRequest
位置限制
指定要搜索的区域。指定区域以外的搜索结果不予显示 返回。
如需设置位置限制参数,请调用
setLocationRestriction()
方法。FindAutocompletePredictionsRequest
将位置偏向或位置限制区域指定为 矩形视口或圆形
圆形由中心点和半径(以米为单位)定义。半径必须在 0.0 和 50000.0(含边界值)。默认值为 0.0。对于位置限制 您必须将半径设置为大于 0.0 的值。否则,该请求会返回 没有匹配的结果。
矩形是一种经纬度视口,表示为 与
low
和high
点对角线。视口被视为 表示它包含其边界。纬度边界 必须介于 -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 不能为空。视口为空会导致错误。- 如果
-
来源
要计算从该起点到终点的直线距离 目标位置(使用
getDistanceMeters()
访问)。如果此值 将不会返回直线距离。必须指定为 经纬度坐标:如需设置 origin 参数,请调用
setOrigin()
方法。FindAutocompletePredictionsRequest
-
区域代码
用于设置响应格式(包括地址格式)的地区代码,已指定为 ccTLD(“顶级域名”) 两个字符的值。大多数 ccTLD 代码都与 ISO 3166-1 代码相同, 但有一些值得注意的例外情况。例如,英国的 ccTLD 为 "uk"(.co.uk),而其 ISO 3166-1 代码为“gb”(从技术层面来讲, “大不列颠及北爱尔兰联合王国”)。
如果您指定的地区代码无效,则 API 会返回
INVALID_ARGUMENT
错误。根据适用法律,该参数可能会影响结果。如需设置地区代码参数,请调用
setRegionCode()
方法。FindAutocompletePredictionsRequest
-
会话令牌
会话令牌是用户生成的字符串,用于跟踪 将“自动补全(新)”调用作为“会话”调用。自动补全功能使用会话令牌来 将用户自动补全搜索的查询和选择阶段归入单独的会话 结算目的。会话将在 用户开始输入查询,并在选择地点时结束。每次会话 可以进行多项查询,并随后选择一个地点。会话 令牌失效;您的应用必须生成新的令牌 。我们建议将会话令牌用于所有程序化交易, 自动补全会话(当您嵌入片段时,或使用 则 API 会自动处理此操作)。
自动补全使用
AutocompleteSessionToken
识别每个会话之后,您的应用应传递一个新的会话令牌。 启动每个新会话,然后将同一令牌和地点 ID 一起传递至 对fetchPlace()
的后续调用 可检索用户所选地点的地点详情。如需设置会话令牌参数,请调用
setSessionToken()
方法。FindAutocompletePredictionsRequest
如需了解详情,请参阅 会话令牌。
自动补全(新)示例
使用位置限制和位置偏向
自动填充(新)默认使用 IP 自定义调整来 控制搜索区域。通过 IP 自定义调整,API 会使用 以自定义结果。您可以选择使用位置信息 限制或位置偏差,但不能 均可指定搜索区域。
位置限制用于指定要搜索的区域。指定范围以外的结果 不会返回任何区域。以下示例使用位置限制将请求限制为 以旧金山为中心、半径为 5000 米的圆形位置限制:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Amoeba") .setLocationRestriction(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
对于位置偏差,位置会充当偏差,这意味着结果会 可返回指定位置,包括指定位置以外的结果。 区域。下一个示例将上一个请求更改为使用位置偏向:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Amoeba") .setLocationBias(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
使用主要类型
使用 primarytypes 参数限制来自某个 请求为表格中列出的特定类型 A 和表格 B。您可以指定 是一个最多包含五个值的数组。如果省略,则返回所有类型。
以下示例指定了“Soccer”的查询字符串并使用
type 参数,用于将结果限定为以下类型的场所
"sporting_goods_store"
:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store"); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Soccer") .setIncludedPrimaryTypes(primaryTypes) .setLocationBias(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
如果省略主要类型参数,则结果可能会包含场所
类,例如 "athletic_field"
。
使用源
如果您在请求中包含 origin 参数(指定为
纬度和经度坐标,API 包含直线距离,
响应中包含从出发地到目的地(使用
getDistanceMeters()
)。
以下示例将原点设置为旧金山的中心:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Amoeba") .setOrigin(center) .setLocationRestriction(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
归因
即使您没有地图,也可以使用自动补全(新)功能。如果 您确实要显示地图,则该地图必须是 Google 地图当您显示预测结果时, 在没有地图的情况下使用自动补全(新)服务, 必须包含在搜索字段/结果中显示的 Google 徽标。对于 请参阅显示 Google 徽标和 提供方说明。