自动补全（新）

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

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

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

系统会向用户显示返回的地点预测结果，以帮助他们选择所需的地点。您可以发出地点详情（新）请求，详细了解所返回的任何地点预测结果。

自动补全（新）请求

您的应用可以通过调用 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 包含最多 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() 方法。

可选参数

  • 主要类型

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

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

    如果出现以下情况，请求会被拒绝并显示 INVALID_REQUEST 错误：

    • 指定了超过五种类型。
    • 指定了任何无法识别的类型。

    如需设置主要类型参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setTypesFilter() 方法。

  • 国家/地区

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

    如果您同时指定了 locationRestriction 和 includedRegionCodes，则结果位于这两个设置的交叉区域内。

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

  • 输入偏移

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

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

  • 位置偏向或位置限制

    您可以指定位置偏向或位置限制（但不能同时指定这两者）来定义搜索区域。您可以将位置限制视为指定结果必须位于的区域，将位置偏向视为指定结果必须位于附近的区域。关键区别在于，在存在位置偏差的情况下，系统可能仍会返回指定区域之外的结果。

    • 位置偏差

      指定要搜索的区域。此位置是作为偏向（而非限制）来使用的，因此系统可能仍会返回指定区域以外的结果。

      如需设置位置偏差参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setLocationBias() 方法。

    • 地理位置限制

      指定要搜索的区域。系统不会返回指定区域以外的结果。

      如需设置地理位置限制参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setLocationRestriction() 方法。

    将位置偏差或位置限制区域指定为矩形视口或圆形。

    • 圆形由中心点和半径（以米为单位）定义。半径必须介于 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 代码相同，但有一些明显的例外。例如，英国的国家代码顶级域名为“uk”(.co.uk)，而其 ISO 3166-1 代码却是“gb”（专指“大不列颠及北爱尔兰联合王国”这一实体）。

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

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

  • 会话令牌

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

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

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

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

自动补全（新）示例

使用地理位置限制和地理位置偏向

自动补全（新）默认使用 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());
        })
    );

使用主要类型

使用主要类型参数可将请求的结果限制为表格 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 徽标和提供方说明。