新一代 Places SDK for Android 现已随着 Places SDK for Android（新）的发布而推出。

此页面由 Cloud Translation API 翻译。

地点自动补全

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

Places SDK for Android 中的自动补全服务会返回地点来响应用户搜索查询。在用户输入内容时，自动填充服务会返回有关地点（如商家、地址、Plus Codes 和地图注点。

您可以通过以下方式向应用中添加自动填充服务：

添加自动补全 widget 以进行保存开发时间并确保提供一致的用户体验。
获取地点预测以编程方式创建打造个性化的用户体验。

添加自动补全 widget

自动补全 widget 是一个具有内置自动补全功能的搜索对话框功能在用户输入搜索字词时，此小部件会显示预测地点列表供您选择。用户做出选择后，系统会返回 Place 实例，然后您的应用可以使用此实例获取有关所选地点的详情。

向应用中添加自动填充小部件的方式有两种：

方法 1：嵌入 AutocompleteSupportFragment。
方式 2：使用 intent 启动自动补全 activity。

选项 1：嵌入 AutocompleteSupportFragment

如需向应用添加 AutocompleteSupportFragment，请按以下步骤操作：

向 activity 的 XML 布局中添加一个 fragment。
向 activity 或 fragment 添加监听器。

向 activity 中添加 AutocompleteSupportFragment

如需向 activity 添加 AutocompleteSupportFragment，请将新的 fragment 添加到 XML 布局。例如：

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />

默认情况下，fragment 没有边框或背景。为了提供一致的视觉外观，请将此 fragment 嵌套到另一个布局元素中，例如 CardView。
如果您使用的是自动补全 fragment，并且需要替换 onActivityResult，则必须调用 super.onActivityResult，否则 fragment 将无法正常运行。

向 activity 添加 PlaceSelectionListener

PlaceSelectionListener 处理返回地点以响应用户的选择。以下代码演示了如何创建对 fragment 的引用以及如何向 AutocompleteSupportFragment 添加监听器：

Kotlin

    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
                as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

Java

    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
            getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

选项 2：使用 intent 启动自动补全 activity

如果您希望应用使用其他导航流程（例如，通过图标（而不是搜索字段）触发自动补全体验），您的应用可以使用 intent 启动自动补全功能。

要使用 Intent 启动自动填充小部件，请执行以下步骤：

使用Autocomplete.IntentBuilder 创建一个 intent，从而传递所需的 Autocomplete 模式。
定义一个 activity 结果启动器 registerForActivityResult，用于启动 intent 并处理结果中用户选择的地点预测。

创建自动补全 intent

以下示例使用 Autocomplete.IntentBuilder 创建 intent，以便将自动填充小部件作为 intent 启动：

Kotlin

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startAutocomplete.launch(intent)

Java

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .build(this);
    startAutocomplete.launch(intent);

当使用 intent 来启动自动填充小部件时，您可以选择叠加模式或全屏显示模式。以下屏幕截图分别显示了每种显示模式：

在叠加模式下显示时，自动补全微件会叠加在通话界面上。 — **图 1**：OVERLAY 模式下的自动填充 widget

在全屏模式下显示时，自动补全 widget 会填满整个屏幕。 — **图 2**：全屏模式下的 Autocomplete widget

针对 intent 结果注册回调

要在用户选择地点后收到通知，请定义 registerForActivityResult() 启动器，用于启动 activity 并处理结果，如以下示例所示。如果用户选择了某个预测的地址，系统将在结果对象中包含的 intent 中提供该地址。由于 intent 是通过 Autocomplete.IntentBuilder 构建的，因此 Autocomplete.getPlaceFromIntent() 方法可以从中提取 Place 对象。

Kotlin

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            Log.i(TAG, "User canceled autocomplete")
        }
    }

Java

private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

以编程方式获取地点预测

您可以创建自定义搜索界面，作为自动填充 widget 提供的界面的替代方案。为此，您的应用必须以编程方式获取地点预测。您的应用可以通过调用 PlacesClient.findAutocompletePredictions()，传递包含以下参数的 FindAutocompletePredictionsRequest 对象，从自动补全 API 获取预测地点名称和/或地址列表：

必需：包含用户输入的文本的 query 字符串。
推荐：AutocompleteSessionToken，用于将用户搜索的查询和选择阶段归入不同的会话，以便进行结算。会话会在用户开始输入时开始并在用户选择地点时结束。
推荐：RectangularBounds 对象，用于指定纬度和经度边界，以将结果限制在指定区域。
可选：一个或多个由两个字母构成的 country 代码 (ISO 3166-1) Alpha-2)，用于表示搜索结果应运达的一个或多个国家/地区受限。
可选：A TypeFilter, 您可以用其将结果限制为指定地点类型。通过支持以下地点类型：
- TypeFilter.GEOCODE - 仅返回地理编码结果，而不是返回商家。使用此请求可以消除指定位置模糊的结果。
- TypeFilter.ADDRESS - 仅返回符合以下条件的自动补全结果：确切地址当您知道用户正在寻找完全指定的地址时，使用此类型。
- TypeFilter.ESTABLISHMENT - 仅返回商家地点。
- TypeFilter.REGIONS - 仅返回与以下某项以下类型：
- LOCALITY
- SUBLOCALITY
- POSTAL_CODE
- COUNTRY
- ADMINISTRATIVE_AREA_LEVEL_1
- ADMINISTRATIVE_AREA_LEVEL_2
- TypeFilter.CITIES - 仅返回与 LOCALITY 或 ADMINISTRATIVE_AREA_LEVEL_3。
可选：一个 LatLng，用于指定请求的来源位置。致电后 setOrigin(), 该服务会返回距离指定地点的距离（以米 (distanceMeters) 为单位）来源（针对响应中的每个自动补全联想查询）。

如需了解地点类型，请参阅地点类型指南。

以下示例展示了对 PlacesClient.findAutocompletePredictions() 的完整调用。

Kotlin

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }

Java

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(new LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

该 API 会在 Task 中返回 FindAutocompletePredictionsResponse。FindAutocompletePredictionsResponse 包含一系列 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 对象。如需详细了解 Places SDK for Android 中的地点 ID，请参阅地点详情。如需了解有关地点 ID 的一般信息，请参阅地点 ID 概览。
getPlaceTypes() 返回与此地点关联的地点类型列表。
getDistanceMeters() 用于返回此地点与指定来源。

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

会话令牌

会话令牌将用户自动补全搜索的查询和选择阶段归入不同的会话，以便进行结算。会话在用户开始输入查询内容时开始，并在用户选择地点时结束。在每个会话中，用户可以输入多项查询内容，并最终选择一个地点。会话结束后，令牌将失效；您的应用必须为每个会话生成一个新的令牌。我们建议将会话令牌用于所有程序化交易，自动补全会话（当您嵌入片段时，或使用则 API 会自动处理此操作）。

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

详细了解会话令牌。

限制自动补全结果

您可以将自动补全结果限制在特定地理区域，和/或对结果进行过滤，以便仅显示一个或多个地点类型，或最多显示五个国家/地区。您可以对自动补全 activity 应用这些约束条件， AutocompleteSupportFragment 和程序化自动补全 API。

如需限制结果，请执行以下操作：

如需优先显示指定区域内的结果，请调用 setLocationBias() （可能仍会返回来自指定区域之外的一些结果。）
如需仅显示指定区域内的结果，请调用 setLocationRestriction()（系统只会返回指定区域内的结果）。
如需仅返回符合特定地点类型的结果，请调用 setTypesFilter()（例如，指定 TypeFilter.ADDRESS 将仅返回具有精确地址的结果）。
如需仅返回最多 5 个指定国家/地区内的结果，请调用 setCountries()。国家/地区必须以兼容 ISO 3166-1 Alpha-2 的双字符国家/地区代码形式传递。

使结果偏向于特定区域

要使自动填充结果偏向于特定的地理区域，请调用 setLocationBias()，传递一个 RectangularBounds。以下代码示例显示在一个 fragment 实例中调用 setLocationBias()，以便使自动填充建议偏向于澳大利亚悉尼的一个地区。

Kotlin

    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

Java

    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

将结果限定为特定区域

如需将自动补全结果限制为特定的地理区域，请调用 setLocationRestriction()，并传递 RectangularBounds。以下代码示例显示在一个 fragment 实例中调用 setLocationRestriction()，以便使自动补全建议偏向于澳大利亚悉尼的一个地区。

Kotlin

    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

Java

    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

注意：此限制仅适用于整个路线、合成结果它可能会根据与地理位置限制重叠。

按地点类型或类型集合过滤结果

您可以限制自动填充请求的结果，使其仅返回特定地点类型。使用地点类型或类型集合指定过滤条件地点类型的表 1、2 和 3 中列示。如果未指定任何类型，系统将返回所有类型。

如需过滤自动补全结果，请调用 setTypesFilter() 来设置过滤条件。

要指定类型或类型集合过滤条件，请执行以下操作：

调用 setTypesFilter()，并指定地点类型中所示表 1 和表 2 中的最多五个类型值。类型值包括由中的常量定义， PlaceTypes。
调用 setTypesFilter() 并指定地点类型中所示表 3 中的类型集合。集合值由 PlaceTypes 中的常量定义。

只能在请求中使用表 3 中的一种类型。如果您指定了表 3 中的值，则无法指定表 1 或表 2 中的值。如果您这样做，则会发生错误。

以下代码示例对 AutocompleteSupportFragment 调用 setTypesFilter()，并指定多个类型值。

Kotlin

    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

Java

    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

以下代码示例展示了如何对 AutocompleteSupportFragment 调用 setTypesFilter()，以便通过指定类型集合来设置一个过滤器，从而仅返回具有精确地址的结果。

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

Java

    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

以下代码示例展示了如何对 IntentBuilder 调用 setTypesFilter()，以便通过指定类型集合来设置一个过滤器，从而仅返回具有精确地址的结果。

Kotlin

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

Java

    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .build(this);

按国家/地区过滤结果

如需将自动补全结果过滤到最多五个国家/地区，请调用 setCountries() 设置国家/地区代码。然后，将过滤器传递给 fragment 或 intent。国家/地区必须以双字符，符合 ISO 3166-1 Alpha-2 标准的国家/地区代码。

以下代码示例展示了如何对 AutocompleteSupportFragment 调用 setCountries()，以便设置一个过滤器，从而仅返回指定国家/地区内的结果。

Kotlin

    autocompleteFragment.setCountries("AU", "NZ")

Java

    autocompleteFragment.setCountries("AU", "NZ");

用量限额

您对 Places API（包括 Places SDK for Android）的使用不再受每日请求次数上限 (QPD) 的限制。不过，以下用量限额仍然适用：

速率限制为 6000 QPM（每分钟请求数）。时间是即所有广告请求的客户端和服务器端请求多个应用。

在应用中显示提供方说明

如果您的应用以编程方式使用自动填充服务，您的界面必须显示“由 Google 强力驱动”或者出现在 Google 品牌地图。
如果您的应用使用自动填充 widget，则无需采取任何其他操作（默认显示所需的提供方说明）。
如果您在按 ID 获取地点后检索并显示其他地点信息，则也必须显示第三方提供方说明。

有关详情，请参阅归因。

地点自动补全优化

本部分介绍了帮助您充分利用地点自动补全服务的最佳实践。

下面列出了一些一般准则：

若要开发可正常运行的界面，最快的方式是使用 Maps JavaScript API Autocomplete widget、Places SDK for Android Autocomplete widget 或 Places SDK for iOS Autocomplete 界面控件。
从一开始就了解重要的地点自动补全数据字段。
位置自定义调整和位置限制字段是可选的，但可能会对自动补全性能产生重大影响。
使用错误处理可确保您的应用在 API 返回错误时妥善降级。
请确保您的应用可以处理没有选择任何内容的情况，并能够让用户继续操作。

费用优化最佳实践

基本费用优化

为了优化地点自动补全服务的使用费用，请在地点详情和地点自动补全 widget 中使用字段掩码，以便仅返回所需的地点数据字段。

高级费用优化

请考虑通过程序化方式实现地点自动补全，以便采用“按请求”定价模式，并请求关于所选地点（而不是地点详情）的 Geocoding API 结果。如果同时满足以下两个条件，与采用“按会话”（基于会话）定价模式相比，将“按请求”定价模式与 Geocoding API 搭配使用的性价比更高：

如果您只需要用户所选地点的纬度/经度或地址，那么采用 Geocoding API 提供此类信息所需的费用会低于调用地点详情。
如果用户平均在不超过四次自动补全预测请求之内选择自动补全预测结果，那么“按请求”定价模式可能会比“按会话”定价模式的性价比更高。

如果在选择符合您需求的地点自动补全实现方面需要帮助，请选择与以下问题的答案相对应的标签页。

除了所选预测结果的地址和纬度/经度外，您的应用是否需要任何其他信息？

是，需要更多详细信息

将基于会话的地点自动补全与地点详情搭配使用。
由于您的应用需要地点名称、商家状态或营业时间等地点详情，因此您的地点自动补全实现应使用会话令牌（以程序化方式构建，或内置到 JavaScript、Android 或 iOS widget 中），总费用为每次会话 0.017 美元，外加相应的地点数据 SKU 费用（具体取决于您申请的地点数据字段）。¹

widget 实现
会话管理功能自动内置于 JavaScript、Android 或 iOS widget 中。这包括针对所选预测结果的“地点自动补全”请求和“地点详情”请求。请务必指定 fields 参数，以确保您只请求所需的地点数据字段。

程序化实现
在“地点自动补全”请求中使用会话令牌。在请求关于所选预测结果的地点详情时，添加以下参数：

“地点自动补全”响应中的地点 ID
“地点自动补全”请求中使用的会话令牌
fields 参数，用于指定您所需的地点数据字段

否，只需要地址和位置信息

对于您的应用，Geocoding API 可能比地点详情性价比更高，具体取决于您使用地点自动补全的性能。每个应用的自动补全效率各有不同，具体取决于用户输入的内容、使用应用所在的位置，以及是否遵循了性能优化最佳实践。

为了回答以下问题，请分析用户在您的应用中选择地点自动补全预测结果之前平均会输入多少个字符。

平均而言，用户是否能够在不超过四次请求之内选择地点自动补全预测结果？

是

在不使用会话令牌的情况下以程序化方式实现地点自动补全，并针对所选的地点预测调用 Geocoding API。
Geocoding API 提供地址和纬度/经度坐标，价格为每个请求 0.005 美元。发出四次地点自动补全 - 按请求结算请求的费用为 0.01132 美元，因此四次请求加上针对所选地点预测调用 Geocoding API 的总费用将为 0.01632 美元，低于按会话结算的自动补全价格（即每次会话 0.017 美元）。¹

您可以考虑采用性能最佳实践，帮助用户以更少的字符找到所需的预测结果。

否

将基于会话的地点自动补全与地点详情搭配使用。
由于您预计在用户选择地点自动补全预测结果之前应用发出的平均请求次数较多，所需费用会超过“按会话”定价模式的费用，因此建议您在实现地点自动补全时，针对“地点自动补全”请求和关联的“地点详情”请求使用会话令牌，总费用为每次会话 0.017 美元。¹

widget 实现
会话管理功能自动内置于 JavaScript、Android 或 iOS widget 中。这包括针对所选预测结果的“地点自动补全”请求和“地点详情”请求。请务必指定 fields 参数，以确保您只请求基本数据字段。

程序化实现
在“地点自动补全”请求中使用会话令牌。在请求关于所选预测结果的地点详情时，添加以下参数：

“地点自动补全”响应中的地点 ID
“地点自动补全”请求中使用的会话令牌
fields 参数，用于指定地址和几何图形等基本数据字段

考虑延迟“地点自动补全”请求
您可以采取一些策略，例如延迟“地点自动补全”请求，直到用户输入前三个或四个字符，从而减少应用发出的请求数量。例如，在用户输入第三个字符后针对每个字符发出“地点自动补全”请求，也就是说，如果用户输入七个字符，然后选择了您发出一次 Geocoding API 请求所获得的预测结果，总费用将为：0.01632 美元（4 * 0.00283 美元 [自动补全 - 按请求结算] + 0.005 美元 [地理编码]）。¹

如果延迟请求会导致平均程序化请求次数低于四次，您可以按照使用 Geocoding API 提高地点自动补全性能的实现指南操作。请注意，如果用户希望每次输入新的字符后都能看到预测结果，可能会将延迟请求视为时间上的延迟。

您可以考虑采用性能最佳实践，帮助用户以较少的字符找到所需的预测结果。

此处所列的费用以美元为单位。如需了解完整的定价信息，请参阅 Google Maps Platform 结算页面。

性能最佳实践

下面的指南介绍了优化地点自动补全性能的方式：

向地点自动补全实现添加国家/地区限制、位置自定义调整和语言偏好设置（适用于程序化实现）。您无需为 widget 进行语言偏好设置，因为它们会从用户的浏览器或移动设备中选择语言偏好设置。
如果地点自动补全附有地图，您可以根据地图视口来设置位置偏向。
如果用户未选择任一自动补全预测结果，通常是因为这些预测结果都不是所需的结果地址，您可以重复使用原始用户输入来尝试获取更相关的结果：
- 如果您希望用户仅输入地址信息，请在调用 Geocoding API 时重复使用原始用户输入。
- 如果您希望用户按名称或地址查询某个地点，请使用“查找地点”请求。如果希望仅显示特定区域内的结果，请使用位置自定义调整。
适合回退到 Geocoding API 的其他场景包括：
- 用户在针对 subpremise 地址的地点自动补全支持不完整的国家/地区（例如捷克、爱沙尼亚和立陶宛）输入 subpremise 地址。例如，捷克地址“Stroupežnického 3191/17, Praha”会在地点自动补全中生成部分预测结果。
- 用户在输入地址时，需要输入路段前缀，例如纽约的“23-30 29th St, Queens”或夏威夷考爱岛“47-380 Kamehameha Hwy, Kaneohe”。

问题排查

尽管应用可能会出现各种各样的错误，但绝大多数错误通常是由配置错误（例如，使用的 API 密钥不正确或 API 密钥配置不正确），或配额错误（您的应用已超出其配额）。请参阅用法更多限制有关配额的信息

使用自动完成控件时发生的错误会在 onActivityResult() 回调。调用 Autocomplete.getStatus() 以获取结果的状态消息。