自动补全（新）

自动补全（新）会返回地点预测结果，以响应包含文本搜索字符串和用于控制搜索区域的地理边界的请求。自动补全功能可以根据所输入内容的完整字词和子字符串进行匹配，从而解析地点名称、地址和 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 度（含）之间：

      • 如果 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 错误。该参数可能会影响根据适用法律的结果。

    如需设置地区代码参数，请在构建 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());
        })
    );

使用主要类型

使用主要类型参数将请求的结果限制为特定类型（如表 A 和表 B 中所述）。您可以指定最多包含五个值的数组。如果省略，则返回所有类型。

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