一切就绪!

着手开发前,请先阅读我们的开发者文档

激活 Google Places API for Android

为帮助您起步,我们将引导您在 Google 开发者控制台中先完成几项任务:

  1. 创建或选择项目
  2. 激活 Google Places API for Android
  3. 创建相应密钥
继续

地点自动填充

Google Places API for Android 中的自动填充服务会返回预测地点,以响应用户搜索查询。 在用户输入搜索内容时,自动填充服务会返回建议地点,例如商家、地址和景点。

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

添加自动填充小部件

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

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

选项 1:嵌入 PlaceAutocompleteFragment 或 SupportPlaceAutocompleteFragment

要向您的应用添加 PlaceAutocompleteFragment,请执行以下步骤:

  1. 向 Activity 的 XML 布局中添加片段。
  2. 向 Activity 或片段中添加侦听器。

向 Activity 中添加 PlaceAutocompleteFragment

要向 Activity 中添加 PlaceAutocompleteFragment,请将名为 com.google.android.gms.location.places.ui.PlaceAutocompleteFragment 的新片段添加到 XML 布局。

例如:

<fragment
  android:id="@+id/place_autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.gms.location.places.ui.PlaceAutocompleteFragment"
  />

注:默认情况下,此片段没有边框或背景。 为了提供一致的视觉外观,请将此片段嵌套到另一个布局元素中,例如 CardView

向 Activity 中添加 PlaceSelectionListener

PlaceSelectionListener 处理返回地点,以响应用户的选择。 以下代码演示如何创建片段引用并向 PlaceAutocompleteFragment 添加侦听器:

PlaceAutocompleteFragment autocompleteFragment = (PlaceAutocompleteFragment)
getFragmentManager().findFragmentById(R.id.place_autocomplete_fragment);

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

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

使用 SupportPlaceAutocompleteFragment(旧版平台)

Google Places API 需要 API 级别 12 或更高级别,才能支持 PlaceAutocompleteFragment 对象。 如果您的目标是低于 API 级别 12 的应用,可通过 SupportPlaceAutocompleteFragment 类访问同一功能。

您还必须包括 Android v4 支持库

要支持 API 级别低于 12 的 Android 版本,请执行以下步骤:

  • 在主 Activity 中扩展 FragmentActivityAppCompatActivity
  • 使用 SupportPlaceAutocompleteFragment 取代 PlaceAutocompleteFragment
  • 使用 getSupportFragmentManager() 取代 getFragmentManager()

选项 2:使用 Intent 启动自动填充 Activity

如果您希望应用使用其他导航流(例如,通过图标而不是通过搜索字段触发自动填充体验),您的应用可通过使用 Intent 启动自动填充。

注:如果要嵌入片段,则不需要执行这些步骤。

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

  1. 使用 PlaceAutocomplete.IntentBuilder 创建 Intent,传递所需的 PlaceAutocomplete 模式。 此 Intent 必须调用 startActivityForResult,在可以识别您的 Intent 的请求代码中传递。

  2. 替换 onActivityResult 回调,以接收所选地点。

创建自动填充 Intent

以下示例显示使用 PlaceAutocomplete.IntentBuilder 创建 Intent,以便将自动填充小部件作为 Intent 启动:

int PLACE_AUTOCOMPLETE_REQUEST_CODE = 1;
...
try {
    Intent intent =
            new PlaceAutocomplete.IntentBuilder(PlaceAutocomplete.MODE_FULLSCREEN)
                    .build(this);
    startActivityForResult(intent, PLACE_AUTOCOMPLETE_REQUEST_CODE);
} catch (GooglePlayServicesRepairableException e) {
    // TODO:Handle the error.
} catch (GooglePlayServicesNotAvailableException e) {
    // TODO:Handle the error.
}

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

When displayed in overlay mode, the autocomplete widget appears superimposed over the calling UI.
图 1:叠加模式下的自动填充小部件 (MODE_OVERLAY)
When displayed in fullscreen mode, the autocomplete widget fills the entire screen.
图 2:全屏模式下的自动填充小部件 (MODE_FULLSCREEN)

替换 onActivityResult 回调

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

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == PLACE_AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = PlaceAutocomplete.getPlace(this, data);
            Log.i(TAG, "Place: " + place.getName());
        } else if (resultCode == PlaceAutocomplete.RESULT_ERROR) {
            Status status = PlaceAutocomplete.getStatus(this, data);
            // TODO:Handle the error.
            Log.i(TAG, status.getStatusMessage());

        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
    }
}

限制自动填充结果

您可以设置自动填充小部件,使结果偏向于特定的地理区域,并且/或者过滤问仅填充一个或更多地点类型的结果。

使结果偏向于特定区域

如需使自动填充结果偏向于特定的地理区域,请执行以下操作:

  • 设置应用 PlaceAutocompleteFragment 实例或 IntentBuilder 实例的 setBoundsBias() 调用,传递 LatLngBounds

以下代码示例显示在一个片段实例中调用 setBoundsBias(),以便使自动填充建议偏向于澳大利亚悉尼的一个地区。

autocompleteFragment.setBoundsBias(new LatLngBounds(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

按地点类型过滤结果

如需将自动填充结果过滤为特定的位置类型,请调用 AutocompleteFilter.Builder 创建新的 AutocompleteFilter,以便调用 setTypeFilter() 来设置要使用的过滤器。

然后,将过滤器传递给片段或 Intent。

以下代码演示如何在 PlaceAutocompleteFragment 上设置 AutocompleteFilter,以便设置一个过滤器,从而仅返回具有精确地址的结果。

AutocompleteFilter typeFilter = new AutocompleteFilter.Builder()
        .setTypeFilter(AutocompleteFilter.TYPE_FILTER_ADDRESS)
        .build();

autocompleteFragment.setFilter(typeFilter);

以下代码示例演示如何在 Intent 上设置 AutocompleteFilter,以便设置一个过滤器,从而仅返回具有精确地址的结果。

AutocompleteFilter typeFilter = new AutocompleteFilter.Builder()
        .setTypeFilter(AutocompleteFilter.TYPE_FILTER_ADDRESS)
        .build();

Intent intent =
        new PlaceAutocomplete.IntentBuilder(PlaceAutocomplete.MODE_FULLSCREEN)
                .setFilter(typeFilter)
                .build(this);

如需了解有关地点类型的信息,请参阅地点类型AutocompleteFilter.Builder 指南。

以编程方式获取地点预测

您可以创建自定义搜索 UI,作为自动填充小部件提供的 UI 的备用 UI。 为此,您的应用必须以编程方式获取地点预测。 您的应用可以通过调用 GeoDataApi.getAutocompletePredictions() 传递以下参数,从自动填充服务中获取预测地点名称和/或地址列表:

  • 必填: 包含用户输入的文本的 query 字符串。
  • 必填: LatLngBounds 对象,可使结果偏向于按纬度和经度范围指定的特定区域。

  • 可选: 包含一系列地点类型的 AutocompleteFilter,您可以使用它将结果限制为一个或多个地点类型。

支持以下地点类型:

- `TYPE_FILTER_NONE` &ndash; 空过滤器;返回所有结果。
- `TYPE_FILTER_GEOCODE` &ndash; 仅返回地理编码结果,而非商家。

使用此请求可以消除指定位置模糊的结果。

- `TYPE_FILTER_ADDRESS` &ndash; 仅返回具有精确地址的自动填充结果。

当您知道用户正在寻找完全指定的地址时,使用此类型。

- `TYPE_FILTER_ESTABLISHMENT` &ndash; 仅返回商家地址。

- `TYPE_FILTER_REGIONS` &ndash; 仅返回匹配以下类型之一的地址:

    - `locality`
    - `sublocality`
    - `postal_code`
    - `country`
    - `administrative_area_level_1`
    - `administrative_area_level_2`

- `TYPE_FILTER_CITIES` &ndash; 仅返回匹配 `locality` 或 `administrative_area_level_3` 的结果。

如需了解有关地点类型的信息,请参阅地点类型AutocompleteFilter.Builder 指南。

下例显示了 GeoDataApi.getAutocompletePredictions() 的简单调用。 有关完整的示例,请参阅示例应用

PendingResult<AutocompletePredictionBuffer> result =
    Places.GeoDataApi.getAutocompletePredictions(mGoogleApiClient, query,
        bounds, autocompleteFilter);

该 API 返回一个 AutocompletePredictionBuffer(在

PendingResult中)。 AutocompletePredictionBuffer 包含表示预测地点的 AutocompletePrediction 对象列表。

如果没有与查询和筛选条件对应的已知地点,缓冲区可能为空。

注:为了防止内存泄漏,必须在应用不再需要 AutocompletePredictionBuffer 对象时将其释放。

请阅读更多关于处理缓冲区的内容。

对于每个预测地点,都可以调用以下方法来检索地点详情:

  • getFullText(CharacterStyle matchStyle) 返回地点描述的完整文本。 它由主要文本和辅助文本组合而成。 例如:"Eiffel Tower, Avenue Anatole France, Paris, France"。 此外,这种方式可让您使用 CharacterStyle.,通过所选样式来突出显示与搜索内容匹配的描述部分。

CharacterStyle 参数为可选参数。 如果不需要任何突出显示,请将其设置为 null。

  • getPrimaryText(CharacterStyle matchStyle) 返回描述地点的主要文本。 这通常是地点的名称。 例如:"Eiffel Tower" 和 "123 Pitt Street"。
  • getSecondaryText(CharacterStyle matchStyle) 返回地点描述的辅助文本。 这很有用,例如在显示自动填充预测时作为第二行显示。 示例: "Avenue Anatole France, Paris, France" 和 "Sydney, New South Wales".
  • getPlaceId() 返回预测地点的地点 ID。 地点 ID 是唯一标识地点的文本标识符,您稍后可用其重新检索 Place 对象。

如需了解有关 Google Places API for Android 中地点 ID 的更多信息,请参阅地点 ID 和详情

如需了解有关地点 ID 的一般信息,请参阅地点 ID 概览

使用限制

在应用中显示提供方说明

  • 如果您的应用以编程方式使用自动填充服务,您的 UI 必须显示提供方说明“由 Google 提供支持”,或在带有 Google 品牌的地图中显示。

  • 如果您的应用使用自动填充小部件,无需采取任何其他操作(默认显示所需的提供方说明)。

  • 如果您在按 ID 获取地点后检索并显示其他地点信息,则也必须显示第三方提供方说明。

如需了解详情,请参阅有关提供方说明的文档。

故障排除

尽管会发生很多错误,但您的应用遇到的大部分错误通常是因配置错误(例如使用的 API 密钥不正确、或 API 密钥配置不正确)或配额错误(您的应用超过其配额)引起的。

如需了解有关配额的详细信息,请参阅使用限制

使用自动填充控制过程中出现的错误会在 onActivityResult() 回调中返回。 调用 PlaceAutocomplete.getStatus() 以获取结果的状态消息。

发送以下问题的反馈:

此网页
location_on
Google Places API for Android