地点自动补全

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

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

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

添加自动补全 widget

自动补全 widget 是一个具有内置自动补全功能的搜索对话框 功能在用户输入搜索字词时,该微件会显示 预测地点。当用户做出选择时, Place 该实例后,您的应用可以使用它来获取有关 所选地点。

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

选项 1:嵌入 AutocompleteSupportFragment

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

  1. 向 activity 的 XML 布局中添加一个 fragment。
  2. 向 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 启动自动填充小部件,请执行以下步骤:

  1. 使用Autocomplete.IntentBuilder 以创建 intent,从而传递所需的 Autocomplete 模式。
  2. 定义 activity 结果启动器 registerForActivityResult 可用于启动 intent 和处理用户所选位置 生成预测。

创建自动补全 intent

以下示例使用 Autocomplete.IntentBuilder 创建一个 intent,以将自动补全 widget 作为 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 启动自动补全 widget 时,您可以选择 叠加模式或全屏显示模式。以下屏幕截图显示了 显示模式:

在叠加模式下显示时,自动补全 widget 会叠加在调用界面之上。
图 1:OVERLAY 模式下的 Autocomplete 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。为此,您的应用必须获取地点预测 以编程方式您的应用可以获得预测地点名称和/或 从 Autocomplete API 检索新地址。 PlacesClient.findAutocompletePredictions()、 通过一个 FindAutocompletePredictionsRequest 对象:

  • 必需:包含用户输入的文本的 query 字符串。
  • 建议:A 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 - 仅返回与 LOCALITYADMINISTRATIVE_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 会返回一个 FindAutocompletePredictionsResponseTaskFindAutocompletePredictionsResponse 包含一系列 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,请参阅 Places SDK for Android,请参阅将 详细信息。普通 有关地点 ID 的信息,请参阅地点 ID 概览
  • getPlaceTypes() 用于返回与此地点相关联的地点类型的列表。
  • getDistanceMeters() 用于返回此地点与 指定来源。

会话令牌

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

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

详细了解会话 令牌

限制自动补全结果

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

如需限制结果,请执行以下操作:

  • 如需优先显示指定区域内的结果,请调用 setLocationBias() (可能仍会返回来自指定区域之外的一些结果。)
  • 要仅显示指定区域内的结果,请调用 setLocationRestriction()(只有指定区域内的结果会显示 返回)。
  • 要仅返回符合特定地点类型的结果,请调用 setTypesFilter()(例如,指定 TypeFilter.ADDRESS 会返回 只返回包含精确地址的结果)。
  • 要仅返回最多五个指定国家/地区内的结果,请调用 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。 以下代码示例展示了如何对setLocationRestriction() fragment 实例,使其自动补全建议偏向悉尼的一个区域, 澳大利亚。

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 中最多五个 type 值 如地点类型部分所示。类型值包括 由 中的常量定义, PlaceTypes

  • 调用 setTypesFilter() 并指定表 3 中的类型集合 请参阅地点类型一文。集合值由 中的 PlaceTypes

    只能在请求中使用表 3 中的一种类型。如果您指定 值,您不能指定表 1 或表 2 中的值。如果 就会出错

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

Kotlin



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

      

Java


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

      

以下代码示例展示了如何对setTypesFilter() AutocompleteSupportFragment 设置过滤条件,以便仅返回符合以下条件的结果: 精确地址。

Kotlin



    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java


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

      

以下代码示例展示了如何对setTypesFilter() IntentBuilder 设置过滤条件,以便仅返回具有精确地址的结果 指定类型集合。

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 标准的国家/地区 代码

以下代码示例展示了如何对setCountries() AutocompleteSupportFragment,设置仅返回 。

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 提供此类信息所需的费用会低于调用地点详情。
  • 如果用户平均在不超过四次自动补全预测请求之内选择自动补全预测结果,那么“按请求”定价模式可能会比“按会话”定价模式的性价比更高。
如果在选择符合您需求的地点自动补全实现方面需要帮助,请选择与以下问题的答案相对应的标签页。

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

是,需要更多详细信息

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

性能最佳实践

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

  • 向地点自动补全实现添加国家/地区限制、位置自定义调整和语言偏好设置(适用于程序化实现)。您无需为 widget 进行语言偏好设置,因为它们会从用户的浏览器或移动设备中选择语言偏好设置。
  • 如果地点自动补全附有地图,您可以根据地图视口来设置位置偏向。
  • 如果用户未选择任一自动补全预测结果,通常是因为这些预测结果都不是所需的结果地址,您可以重复使用原始用户输入来尝试获取更相关的结果: 适合回退到 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() 以获取状态 消息。