地点自动补全

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

Places SDK for Android 中的自动补全服务会返回地点预测结果,以响应用户搜索查询。在用户输入内容时,自动补全服务会返回有关商家、地址、Plus Code 和地图注点等地点的建议。

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

添加自动补全 widget

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

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

选项 1:嵌入 AutocompleteSupportFragment

如需将 AutocompleteSupportFragment 添加到您的应用,请按以下步骤操作:

  1. 向 activity 的 XML 布局添加 fragment。
  2. 向 activity 或 fragment 添加监听器。

向 activity 添加 AutocompleteSupportFragment

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

<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:“叠加”模式下的自动补全 widget
在全屏模式下显示时,自动补全 widget 会填满整个屏幕。
图 2:全屏模式下的自动补全 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 对象,从 Autocomplete API 中获取预测地点名称和/或地址的列表:

  • 必需:包含用户输入的文本的 query 字符串。
  • 推荐AutocompleteSessionToken,用于将用户搜索的查询和选择阶段划分为独立的会话,以便进行结算。会话在用户开始输入查询内容时开始,并在用户选择地点时结束。
  • 推荐:一个 RectangularBounds 对象,用于指定纬度和经度边界,以将结果限制在指定区域
  • 可选:一个或多个由两个字母组成的国家/地区代码 (ISO 3166-1 Alpha-2),表明结果应限制在哪个国家或地区。
  • 可选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 会在 Task 中返回 FindAutocompletePredictionsResponseFindAutocompletePredictionsResponse 包含表示预测地点的 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 对象。如需详细了解 Places SDK for Android 中的地点 ID,请参阅地点详情。如需了解地点 ID 的一般信息,请参阅地点 ID 概览
  • getPlaceTypes() 会返回与此地点相关联的地点类型列表。
  • getDistanceMeters() 会返回该地点与请求中指定的出发地之间的直线距离(以米为单位)。

会话令牌

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

Places SDK for Android 使用 AutocompleteSessionToken 来标识每个会话。您的应用应在开始每个新会话时传递一个新的会话令牌,然后在后续调用 fetchPlace() 时传递同一令牌以及地点 ID,以检索用户所选地点的地点详情。

详细了解会话令牌

限制自动补全结果

您可以将自动补全结果限制在特定地理区域,并/或过滤结果以选择一个或多个地点类型或最多五个国家/地区。您可以对自动补全 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。以下代码示例展示了如何对 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 中的最多五个 type 值。类型值由 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) 的限制。不过,以下用量限额仍然适用:

  • 速率限制为 6,000 QPM(每分钟请求数)。计算方式为使用同一项目的凭据的所有应用的客户端和服务器端请求的总和。

在应用中显示提供方说明

  • 如果您的应用以程序化方式使用自动补全服务,您的界面必须显示“Powered by 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() 可获取结果的状态消息。