地点自动补全

选择平台Android iOS JavaScript Web 服务

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

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

添加自动补全微件

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

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

选项 1:嵌入 AutocompleteSupportFragment

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

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

将 AutocompleteSupportFragment 添加到 Activity

如需向 Activity 添加 AutocompleteSupportFragment,请在 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 将无法正常运行。

将 PlaceSelectionListener 添加到 Activity

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

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);
        }
    });

      

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")
        }
    })

      

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

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

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

  1. 使用 Autocomplete.IntentBuilder 创建 intent,并传递所需的 Autocomplete 模式。intent 必须调用 startActivityForResult,并传入标识 intent 的请求代码。
  2. 替换 onActivityResult 回调以接收所选地点。

创建自动补全 intent

以下示例展示了如何使用 Autocomplete.IntentBuilder 创建 intent,以将自动补全微件作为 intent 启动:

Java


    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // 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);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // 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)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

使用 intent 启动自动补全微件时,您可以选择叠加层模式或全屏显示模式。以下屏幕截图分别显示了每种显示模式:

在叠加模式下显示时,自动补全 widget 会叠加在发起调用的界面上。
图 1:叠加模式下的自动补全微件
在全屏模式下显示时,自动补全微件会填满整个屏幕。
图 2:全屏模式下的自动补全微件

替换 onActivityResult 回调

如需在用户选择地点时收到通知,您的应用应替换 Activity 的 onActivityResult(),并检查您为 intent 传递的请求代码,如以下示例所示。

Java


@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

Kotlin


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

以编程方式获取地点预测

您可以创建自定义搜索界面,作为自动补全微件提供的界面的替代方案。为此,您的应用必须以编程方式获取地点预测。您的应用可以通过调用 PlacesClient.findAutocompletePredictions() 并传递带有以下参数的 FindAutocompletePredictionsRequest 对象,通过自动补全 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() 的完整调用。

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(TypeFilter.ADDRESS.toString()))
        .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());
        }
    });

      

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(TypeFilter.ADDRESS.toString()))
            .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)
            }
        }

      

该 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(),以将自动填充建议偏向于澳大利亚悉尼区域。

Java


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

      

Kotlin


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

      

将结果限制为特定区域

如需将自动补全结果限制为特定地理区域,请调用 setLocationRestriction(),并传递 RectangularBounds。以下代码示例展示了如何针对 Fragment 实例调用 setLocationRestriction(),以将自动填充建议偏向于澳大利亚悉尼区域。

Java


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

      

Kotlin


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

      

注意:此限制仅适用于整个路线,可能会根据与位置限制重叠的路线返回位于矩形边界之外的合成结果。

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

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

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

如需指定类型或类型集合过滤条件,请执行以下操作:

  • 调用 setTypesFilter() 并指定表 1 和表 2 中的最多 5 个 type 值(显示在地点类型上)。类型值由 PlaceTypes 中的常量定义。

  • 调用 setTypesFilter() 并指定表 3 中的类型集合(显示在地点类型上)。集合值由 PlaceTypes 中的常量定义。

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

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

Java


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

      

Kotlin


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

      

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

Java


    autocompleteFragment.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()));

      

Kotlin


    autocompleteFragment.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))

      

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

Java


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

      

Kotlin


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

按国家/地区过滤结果

如需按多达五个国家/地区过滤自动补全结果,请调用 setCountries() 以设置国家/地区代码。然后,将过滤器传递给 fragment 或 intent。国家/地区必须以两个字符且符合 ISO 3166-1 Alpha-2 规范的国家/地区代码的形式传递。

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

Java


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

      

Kotlin


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

      

用量限额

Places API(包括 Places SDK for Android)的使用不再受每日请求数上限 (QPD) 的限制。不过,以下用量限额仍然适用:

  • 速率限制为每秒 100 次请求 (QPS)。计算方法是使用同一项目的凭据的所有应用的客户端和服务器端请求的总和。

在应用中显示提供方说明

  • 如果您的应用以编程方式使用自动补全服务,您的界面必须显示“由 Google 提供支持”提供方信息,或者显示在 Google 品牌地图中。
  • 如果您的应用使用自动补全微件,则无需执行任何其他操作(默认显示所需的提供方说明)。
  • 如果您在按 ID 获取地点后检索并显示其他地点信息,则也必须显示第三方提供方信息。

如需了解详情,请参阅有关归因的文档。

地点自动补全优化

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

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

  • 若要开发可正常运行的界面,最快的方式是使用 Maps JavaScript API Autocomplete widget、Places SDK for Android Autocomplete widget 或 Places SDK for iOS 自动补全界面控件
  • 从一开始就了解重要的地点自动补全数据字段
  • 位置自定义调整和位置限制字段是可选的,但可能会对自动补全性能产生重大影响。
  • 使用错误处理可确保您的应用在 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 地址。例如,自动补全功能不支持美国地址“123 Bowdoin St #456, Boston MA, USA”(自动补全功能仅支持澳大利亚、新西兰和加拿大的 subpremise 地址。这三个国家/地区支持的地址格式包括“9/321 Pitt Street, Sydney, New South Wales, Australia”“14/19 Langana Avenue, Browns Bay, Auckland, New Zealand”或“145-112 Renfrew Dr, Markham, Ontario, Canada”)。
    • 用户在输入地址时,需要输入路段前缀,例如纽约的“23-30 29th St, Queens”或夏威夷考爱岛“47-380 Kamehameha Hwy, Kaneohe”。

问题排查

虽然会发生各种错误,但您的应用可能会遇到的大多数错误通常是由于配置错误(例如,使用了错误的 API 密钥或 API 密钥配置不正确)或配额错误(您的应用已超出其配额)导致的。如需详细了解配额,请参阅使用限制

使用自动补全控件时发生的错误会在 onActivityResult() 回调中返回。调用 Autocomplete.getStatus() 可获取结果的状态消息。