此页面由 Cloud Translation API 翻译。

自动补全（新）

请选择平台： 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());
        })
    );

注意：如需详细了解如何初始化 PlacesClient，请参阅初始化 Places API 客户端。

自动补全（新）响应

该 API 会返回一个 FindAutocompletePredictionsResponse 以 Task。通过 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。自动补全（新）服务根据此字符串返回候选匹配项，并按照感受到的相关性。

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

可选参数

主要类型

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

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

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

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

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

如需设置“国家/地区”参数，请调用 setCountries() 方法。FindAutocompletePredictionsRequest
输入偏移

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

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

您可以指定位置偏向或位置限制（但不能同时设置这两者）来定义搜索区域。可以将位置限制视为结果所在的区域，以及位置偏差，用于指定结果必须靠近的区域。主要区别在于存在位置偏向，则系统可能仍会返回指定区域以外的结果。
- 位置偏向
  
  指定要搜索的区域。这个位置只是一种偏见，而不是限制，因此但指定区域以外的地方仍可以返回。
  
  如需设置位置自定义调整参数，请调用 setLocationBias() 方法。FindAutocompletePredictionsRequest
- 位置限制
  
  指定要搜索的区域。指定区域以外的搜索结果不予显示返回。
  
  如需设置位置限制参数，请调用 setLocationRestriction() 方法。FindAutocompletePredictionsRequest
将位置偏向或位置限制区域指定为矩形视口或圆形
- 圆形由中心点和半径（以米为单位）定义。半径必须在 0.0 和 50000.0（含边界值）。默认值为 0.0。对于位置限制您必须将半径设置为大于 0.0 的值。否则，该请求会返回没有匹配的结果。
- 矩形是一种经纬度视口，表示为与low和high点对角线。视口被视为表示它包含其边界。纬度边界必须介于 -90 度（含）到 90 度（含）之间，且经度范围必须为必须介于 -180 度到 180 度之间（包括 -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 都必须填充，并且所表示的 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 徽标和提供方说明。

自动补全（新）

“自动补全（新）”请求

自动补全（新）响应

必需参数

查询

可选参数

主要类型

国家/地区

输入偏移

位置偏向或位置限制

位置偏向

位置限制

来源

区域代码

会话令牌

自动补全（新）示例

使用位置限制和位置偏向

使用主要类型

使用源

归因