自动补全(新)

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

自动补全(新)会在以下位置返回地点预测: 对包含文本搜索字符串和地理边界的请求的响应 用于控制搜索区域的控件。自动补全可以匹配 对输入的完整字词和子字符串进行解析,从而解析地点名称、地址和 plus 代码。您的应用可以发送查询 以实时提供地点和查询预测。

例如,您可以调用 Autocomplete,使用 包含部分用户输入“Sicilian piz”以及搜索区域的字符串 仅限加利福尼亚州旧金山。然后,响应中包含地点列表 与搜索字符串和搜索区域匹配的联想查询(如餐馆) 名为“西西里披萨厨房”

返回的地点预测结果旨在呈现给用户,以帮助 选择所需地点您可以创建地点详情 (新)请求以获取更多 返回的任何地点预测的相关信息。

“自动补全(新)”请求

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

自动补全(新)响应

该 API 会返回一个 FindAutocompletePredictionsResponseTask。 通过 FindAutocompletePredictionsResponse 包含最多五个 AutocompletePrediction 对象来表示预测的地点。如果没有 与查询和过滤条件对应的已知位置。

对于每个预测地点,您都可以调用以下方法来检索地点 详细信息:

  • getFullText(CharacterStyle) 用于返回地点说明的完整文本。这是由 主要文本和辅助文本示例:“Eiffel Tower, Avenue Anatole France, Paris, France”。此外,您还可以通过此方法突出显示 与搜索内容相符的说明,并使用 CharacterStyleCharacterStyle 参数是可选的。如果不需要,请将其设置为 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。 自动补全(新)服务 根据此字符串返回候选匹配项,并按照 感受到的相关性。

    如需设置查询参数,请调用 setQuery() 方法。FindAutocompletePredictionsRequest

可选参数

  • 主要类型

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

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

    如果出现以下情况,则请求将被拒绝并出现 INVALID_REQUEST 错误:

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

    如需设置主要类型参数,请调用 setTypesFilter() 方法。FindAutocompletePredictionsRequest

  • 国家/地区

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

    如果您同时指定 locationRestrictionincludedRegionCodes, 结果就会出现在两种设置的交集区域中。

    如需设置“国家/地区”参数,请调用 setCountries() 方法。FindAutocompletePredictionsRequest

  • 输入偏移

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

    如需设置输入偏移参数,请调用 setInputOffset() 方法。FindAutocompletePredictionsRequest

  • 位置偏向或位置限制

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

    • 位置偏向

      指定要搜索的区域。这个位置只是一种偏见,而不是限制,因此 但指定区域以外的地方仍可以返回。

      如需设置位置自定义调整参数,请调用 setLocationBias() 方法。FindAutocompletePredictionsRequest

    • 位置限制

      指定要搜索的区域。指定区域以外的搜索结果不予显示 返回。

      如需设置位置限制参数,请调用 setLocationRestriction() 方法。FindAutocompletePredictionsRequest

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

    • 圆形由中心点和半径(以米为单位)定义。半径必须在 0.0 和 50000.0(含边界值)。默认值为 0.0。对于位置限制 您必须将半径设置为大于 0.0 的值。否则,该请求会返回 没有匹配的结果。

    • 矩形是一种经纬度视口,表示为 与lowhigh点对角线。视口被视为 表示它包含其边界。纬度边界 必须介于 -90 度(含)到 90 度(含)之间,且经度范围必须为 必须介于 -180 度到 180 度之间(包括 -180 度和 180 度):

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

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

  • 来源

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

    如需设置 origin 参数,请调用 setOrigin() 方法。FindAutocompletePredictionsRequest

  • 区域代码

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

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

    如需设置地区代码参数,请调用 setRegionCode() 方法。FindAutocompletePredictionsRequest

  • 会话令牌

    会话令牌是用户生成的字符串,用于跟踪 将“自动补全(新)”调用作为“会话”调用。自动补全功能使用会话令牌来 将用户自动补全搜索的查询和选择阶段归入单独的会话 结算目的。会话将在 用户开始输入查询,并在选择地点时结束。每次会话 可以进行多项查询,并随后选择一个地点。会话 令牌失效;您的应用必须生成新的令牌 。我们建议将会话令牌用于所有程序化交易, 自动补全会话(当您嵌入片段时,或使用 则 API 会自动处理此操作)。

    自动补全使用 AutocompleteSessionToken 识别每个会话之后,您的应用应传递一个新的会话令牌。 启动每个新会话,然后将同一令牌和地点 ID 一起传递至 对 fetchPlace() 的后续调用 可检索用户所选地点的地点详情。

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

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

自动补全(新)示例

使用位置限制和位置偏向

自动填充(新)默认使用 IP 自定义调整来 控制搜索区域。通过 IP 自定义调整,API 会使用 以自定义结果。您可以选择使用位置信息 限制位置偏差,但不能 均可指定搜索区域。

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