此页面由 Cloud Translation API 翻译。

自动补全（新）

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

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

例如，您可以使用包含部分用户输入的字符串“Sicilian piz”来调用自动补全功能，并将搜索区域限定为加利福尼亚州旧金山。然后，响应中包含与搜索字符串和搜索区域匹配的地点预测列表，例如名为“西西里披萨厨房”的餐厅。

系统会向用户显示返回的地点预测结果，以帮助他们选择所需的地点。您可以发出地点详情（新）请求，以获取有关返回的任何地点预测结果的更多信息。

“自动补全（新）”请求

通过调用 PlacesClient.findAutocompletePredictions() 并传递 FindAutocompletePredictionsRequest 对象，您的应用可以从 Autocomplete API 获取预测地点名称和/或地址的列表。以下示例展示了对 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 会在 Task 中返回 FindAutocompletePredictionsResponse。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。自动补全（新）服务会根据此字符串返回候选匹配项，并按照结果的相关程度对其进行排序。

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

可选参数

主要类型

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

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

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

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

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

要设置国家/地区参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setCountries() 方法。
输入偏移

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

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

您可以指定位置偏向或位置限制（但不能同时指定两者），以定义搜索区域。可以将位置限制视为指定结果必须位于哪个区域，而将位置偏向视为指定结果必须靠近的区域。主要区别在于，在使用位置偏向时，可能仍会返回指定区域以外的结果。
- 位置偏向
  
  指定要搜索的区域。此位置起到偏差的作用（而非限制），因此指定区域以外的结果可能仍会返回。
  
  要设置位置自定义调整参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setLocationBias() 方法。
- 位置限制
  
  指定要搜索的区域。指定区域以外的结果不会返回。
  
  如需设置位置限制参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setLocationRestriction() 方法。
将位置偏向或位置限制区域指定为矩形视口或圆形。
- 圆形由中心点和半径（以米为单位）定义。半径必须介于 0.0 和 50000.0 之间（含 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() 访问）。如果省略此值，将不会返回直线距离。必须指定为纬度和经度坐标：

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

用于设置响应格式的地区代码（包括地址格式），指定为 ccTLD（“顶级域名”）双字符值。大多数 ccTLD 代码都与 ISO 3166-1 代码相同，但也有一些需要注意的例外情况。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（特指“大不列颠及北爱尔兰联合王国”）。

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

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

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

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

自动补全功能使用 AutocompleteSessionToken 来标识每个会话。您的应用应在开始每个新会话时传递新的会话令牌，然后在后续调用 fetchPlace() 时传递同一令牌和地点 ID，以检索用户所选地点的地点详情。

要设置会话令牌参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setSessionToken() 方法。

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

自动补全（新）示例

使用位置限制和位置偏向

自动补全（新）默认使用 IP 自定义调整来控制搜索区域。借助 IP 自定义调整，API 使用设备的 IP 地址来调整结果。您可以视需要使用位置限制或位置偏向（但不能同时使用这两者）来指定要搜索的区域。

位置限制用于指定要搜索的区域。指定区域以外的结果不会返回。以下示例使用位置限制将请求限制为以旧金山为中心、半径 5,000 米的环形位置限制：

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());
        })
    );

使用主要类型

使用 primary types 参数将请求结果限制为某种类型，如表 A 和表 B 中列出的类型。您可以指定最多包含五个值的数组。如果省略，则返回所有类型。

以下示例指定了“Soccer”的查询字符串，并使用 primary 类型参数将结果限制为 "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 徽标和提供方信息。

自动补全（新）

“自动补全（新）”请求

自动补全（新）响应

必需参数

查询

可选参数

主要类型

国家/地区

输入偏移

位置偏向或位置限制

位置偏向

位置限制

原点

区域代码

会话令牌

自动补全（新）示例

使用位置限制和位置偏向

使用主要类型

使用源

归因