此页面由 Cloud Translation API 翻译。

自动补全（新）

请选择平台： Android iOS JavaScript 网络服务

自动补全（新）会在以下位置返回地点预测：对包含文本搜索字符串和地理边界的请求的响应用于控制搜索区域的控件。自动补全功能可以根据输入内容的完整字词和子字符串进行匹配，从而解析地点名称、地址和 Plus Codes。您的应用可以在用户输入内容时发送查询，从而即时进行地点和查询预测。

例如，您可以调用 Autocomplete，使用包含部分用户输入“Sicilian piz”以及搜索区域的字符串仅限加利福尼亚州旧金山。然后，响应中会包含与搜索字符串和搜索区域匹配的地点预测列表，例如名为“Sicilian Pizza Kitchen”的餐厅。

返回的地点预测结果旨在呈现给用户，以帮助选择所需地点您可以发出地点详情（新）请求，详细了解所返回的任何地点预测结果。

自动补全（新）请求

您的应用可以获得预测地点名称和/或从 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());
        })
    );

注意：如需详细了解如何初始化 PlacesClient，请参阅初始化 Places API 客户端。

自动补全（新）响应

该 API 会在 Task 中返回 FindAutocompletePredictionsResponse。FindAutocompletePredictionsResponse 包含最多 5 个表示预测地点的 AutocompletePrediction 对象的列表。如果没有与查询和过滤条件对应的已知地点，列表可能为空。

对于每个预测地点，都可以调用以下方法来检索地点详情：

getFullText(CharacterStyle) 用于返回地点说明的完整文本。它由主要文本和辅助文本组合而成。示例：“Eiffel Tower, Avenue Anatole France, Paris, France”。此外，这种方法可让您使用 CharacterStyle，通过所选样式来突出显示与搜索内容匹配的描述部分。CharacterStyle 参数是可选的。如果不需要，请将其设置为 null 任何突出显示的内容。
getPrimaryText(CharacterStyle) 用于返回描述地点的主要文本。这通常是地点的名称。示例：“埃菲尔铁塔”和“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。自动补全（新）服务根据此字符串返回候选匹配项，并按照感受到的相关性。

如需设置查询参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setQuery() 方法。

可选参数

主要类型

类型中最多五个类型值的列表表 A 或表 B 用于过滤响应中返回的地点。地点必须与某个指定的主要类型值匹配，才能包含在响应中。

一个地点只能有一个主要类型表 A 或表 B 关联的。例如，主要类型可能是 "mexican_restaurant" 或 "steak_house"。

如果出现以下情况，则请求将被拒绝并出现 INVALID_REQUEST 错误：
- 指定了超过五种类型。
- 指定了所有无法识别的类型。
如需设置主要类型参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setTypesFilter() 方法。
国家/地区

仅包含来自指定国家/地区列表的结果，这些国家/地区列表最多指定为 15 个 ccTLD（“顶级域名”）两个字符的值。如果省略，则不会对响应应用任何限制。例如：将区域限制为德国和法国：

如果您同时指定 locationRestriction 和 includedRegionCodes，结果位于两种设置的交集区域中。

如需设置“国家/地区”参数，请调用 setCountries() 方法。FindAutocompletePredictionsRequest
输入偏移

从零开始的 Unicode 字符偏移量，表示查询中的光标位置。游标位置可能会影响返回的预测结果。如果为空，则默认为查询的长度。

如需设置输入偏移参数，请调用 setInputOffset() 方法。FindAutocompletePredictionsRequest
位置偏向或位置限制

您可以指定位置偏向或位置限制（但不能同时指定这两者）来定义搜索区域。可以将位置限制视为结果所在的区域，以及位置偏差，指定结果必须靠近的区域。主要区别在于存在位置偏向，则系统可能仍会返回指定区域以外的结果。
- 位置偏向
  
  指定要搜索的区域。这个位置只是一种偏见，而不是限制，因此但指定区域以外的地方仍可以返回。
  
  如需设置位置自定义调整参数，请调用 setLocationBias() 方法。FindAutocompletePredictionsRequest
- 位置限制
  
  指定要搜索的区域。系统不会返回指定区域以外的结果。
  
  如需设置地理位置限制参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setLocationRestriction() 方法。
将位置偏向或位置限制区域指定为矩形视口或圆形
- 圆形由中心点和半径（以米为单位）定义。半径必须在 0.0 和 50000.0（含边界值）。默认值为 0.0。对于地理位置限制，您必须将半径设置为大于 0.0 的值。否则，该请求会返回没有匹配的结果。
- 矩形是纬度-经度视口，表示为两个对角的 low 和 high 点。视口被视为表示它包含其边界。纬度边界必须介于 -90 度和 90 度（包括这两个数值）之间，经度边界必须介于 -180 度和 180 度（包括这两个数值）之间：
  
  注意：支持的偏差类型因您使用的 SDK 版本而异。CircularBounds 仅适用于“自动补全（新）”。
  - 如果 low = high，视口由该单点组成。
  - 如果 low.longitude > high.longitude，则经度范围会反转（视口跨越 180 度经线）。
  - 如果 low.longitude = -180 度且 high.longitude = 180 度，则视口包含所有经度。
  - 如果 low.longitude = 180 度且 high.longitude = -180 度，则经度范围为空。
  必须填充 low 和 high，并且表示的框不能为空。空视口会导致错误。
来源

要计算从该起点到终点的直线距离目标位置（使用 getDistanceMeters() 访问）。如果此值将不会返回直线距离。必须指定为经纬度坐标：

如需设置 origin 参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setOrigin() 方法。
区域代码

用于设置响应格式（包括地址格式）的地区代码，已指定为 ccTLD（“顶级域名”）两个字符的值。大多数 ccTLD 代码与 ISO 3166-1 代码相同，但有一些明显的例外。例如，英国的 ccTLD 为 "uk"(.co.uk)，而其 ISO 3166-1 代码为“gb”（从技术层面来讲， “大不列颠及北爱尔兰联合王国”）。

注意：地区代码旨在表示请求的来源地区而不一定是查询的目标区域。

如果您指定的地区代码无效，则 API 会返回 INVALID_ARGUMENT 错误。根据适用法律，该参数可能会影响结果。

如需设置地区代码参数，请调用 setRegionCode() 方法。FindAutocompletePredictionsRequest
会话令牌

会话令牌是用户生成的字符串，用于跟踪将“自动补全（新）”调用作为“会话”调用。自动补全功能使用会话令牌将用户自动补全搜索的查询和选择阶段归入不同的会话，以便进行结算。会话将在用户开始输入查询，并在选择地点时结束。每次会话可以进行多项查询，并随后选择一个地点。会话令牌失效；您的应用必须生成新的令牌。我们建议您针对所有程序化自动补全会话使用会话令牌（当您嵌入 fragment 或使用 intent 启动自动补全时，API 会自动处理此事宜）。

自动补全功能使用 AutocompleteSessionToken 来识别每个会话。您的应用应在开始每个新会话时传递新的会话令牌，然后在随后对 fetchPlace() 的调用中传递该令牌以及地点 ID，以检索用户选择的地点的地点详情。

如需设置会话令牌参数，请调用 setSessionToken() 方法。FindAutocompletePredictionsRequest

如需了解详情，请参阅会话令牌。

自动补全（新）示例

使用位置限制和位置偏向

自动填充（新）默认使用 IP 自定义调整来控制搜索区域。使用 IP 偏向时，API 会使用设备的 IP 地址来偏向结果。您可以选择使用位置信息限制或位置偏差，但不能均可指定搜索区域。

位置限制用于指定要搜索的区域。指定范围以外的结果不会返回任何区域。以下示例使用位置限制将请求限制为以旧金山为中心、半径为 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 徽标和提供方说明。

自动补全（新）

自动补全（新）请求

自动补全（新）响应

必需参数

查询

可选参数

主要类型

国家/地区

输入偏移

位置偏向或位置限制

位置偏向

位置限制

来源

区域代码

会话令牌

自动补全（新）示例

使用位置限制和位置偏向

使用主要类型

使用来源

归因