自动补全(新)

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

“自动补全(新)”功能会针对包含文本搜索字符串和用于控制搜索区域的地理边界的请求返回地点预测结果。自动补全功能可以匹配输入内容的完整字词和子字符串,解析地名、地址和Plus Code。您的应用可以在用户输入内容时发送查询,以便动态提供地点和查询预测结果。

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

返回的地点预测结果旨在向用户显示,以帮助他们选择所需的地点。您可以发出地点详情(新)请求,详细了解返回的任何地点预测结果。

自动补全(新)请求

您的应用可以通过调用 PlacesClient.findAutocompletePredictions() 并传递 FindAutocompletePredictionsRequest 对象,从自动补全 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 中返回 FindAutocompletePredictionsResponseFindAutocompletePredictionsResponse 包含最多 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 Code。 自动补全(新)服务会根据此字符串返回匹配候选项,并根据感知相关性对结果进行排序。

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

可选参数

  • 主要类型

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

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

    如果出现以下情况,系统会拒绝请求并显示 INVALID_REQUEST 错误:

    • 指定了超过 5 种类型。
    • 指定所有无法识别的类型。

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

  • 国家/地区

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

    如果您同时指定 locationRestrictionincludedRegionCodes,则结果位于这两项设置的交集区域内。

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

  • 输入偏移

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

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

  • 位置偏向或位置限制

    您可以指定地理偏向或地理限制(但不能同时指定这两者)来定义搜索区域。您可以将位置限制视为指定结果必须位于的区域,将位置偏向视为指定结果必须靠近的区域。主要区别在于,在存在位置偏差的情况下,系统可能仍会返回指定区域之外的结果。

    • 位置偏差

      指定要搜索的区域。此位置是偏向,而非限制,因此系统可能仍会返回指定区域之外的结果。

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

    • 地理位置限制

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

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

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

    • 圆形由中心点和半径(以米为单位)定义。半径必须介于 0.0 到 50000.0 之间(包括这两个数值)。默认值为 0.0。对于地理位置限制,您必须将半径设置为大于 0.0 的值。否则,请求将返回无结果。

    • 矩形是纬度-经度视口,表示为两个对角线相反的 lowhigh 点。视口被视为封闭区域,即包含其边界。纬度边界必须介于 -90 到 90 度之间(包括这两个数值),经度边界必须介于 -180 到 180 度之间(包括这两个数值):

      • 如果 low = high,则视口由该单个点组成。
      • 如果 low.longitude > high.longitude,则经度范围会反转(视口跨越 180 度经线)。
      • 如果 low.longitude = -180 度且 high.longitude = 180 度,则视口包含所有经度。
      • 如果 low.longitude = 180 度且 high.longitude = -180 度,则经度范围为空。

      必须填充 lowhigh,并且表示的框不能为空。空视口会导致错误。

  • 来源

    用于计算到目的地的直线距离的原点(使用 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 地址来偏向结果。您可以选择使用地理位置限制地理位置偏向(但不能同时使用这两者)来指定要搜索的区域。

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