您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 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. 新增一個片段到您活動的 XML 版面配置。
  2. 新增一個接聽程式到您的活動或片段。

新增 PlaceAutocompleteFragment 到活動

若要新增 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

新增 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 層級 21 以前的應用程式為目標,您可以透過 SupportPlaceAutocompleteFragment 類別存取相同的功能。 您也必須包含 Android v4 支援程式庫。 若要支援 API 層級 12 以前的 Android 版本,請遵循以下步驟:

  • 在您的主要活動中延伸 FragmentActivityAppCompatActivity
  • 使用 SupportPlaceAutocompleteFragment,而不使用 PlaceAutocompleteFragment
  • 使用 getSupportFragmentManager(),而不使用 getFragmentManager()

選項 2:使用調用請求來啟動自動完成活動

如果您希望您的應用程式使用不一樣的導覽流程(例如,從圖示觸發自動完成,而不是從搜尋欄位觸發),您可以使用調用請求來啟動自動完成。

注意:如果您是嵌入片段,則不需要這些步驟。

若要使用調用請求來啟動自動完成小工具,請遵循以下步驟:

  1. 使用 PlaceAutocomplete.IntentBuilder 建立調用請求,傳遞需要的 PlaceAutocomplete 模式。 調用請求必須呼叫 startActivityForResult,在識別您的調用請求的要求程式碼中傳遞。

  2. 覆寫 onActivityResult 回呼,以接收所選的地點。

建立自動完成調用請求

以下範例顯示使用 PlaceAutocomplete.IntentBuilder 建立調用請求,以將自動完成小工具啟動為調用請求:

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.
}

使用調用請求來啟動自動完成小工具時,可以選擇重疊或全螢幕顯示模式。 下列螢幕擷取畫面分別顯示各個顯示模式:

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(),檢查您已傳遞給您的調用請求的要求程式碼,如下列範例所示:

@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 實例的 setBoundsBias(),或是 IntentBuilder 實例,並傳遞 LatLngBounds。 下列程式碼範例顯示在片段實例上呼叫 setBoundsBias(),使其自動完成建議偏向澳洲雪梨的區域。
autocompleteFragment.setBoundsBias(new LatLngBounds(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

依照地點類型篩選結果

若要依照特定地點類型來篩選自動完成結果,請呼叫 AutocompleteFilter.Builder 來建立新的 AutocompleteFilter,並呼叫 setTypeFilter() 來設定要使用的篩選器。 然後,將篩選器傳遞到片段或調用請求。

下列程式碼範例顯示在 PlaceAutocompleteFragment 上的AutocompleteFilter 設定,以設定僅傳回有精確地址結果的篩選器。

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

autocompleteFragment.setFilter(typeFilter);

下列程式碼範例顯示在調用請求上的 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。 如果要這樣做,您的應用程式必須以程式設計方式取得地點預測。 您的應用程式可以從自動完成服務取得預測地點名稱和/或地址的清單,方法是呼叫 GeoDataApi.getAutocompletePredictions(),並傳遞下列參數:

  • 必要: 包含使用者輸入之文字的 query 字串。
  • 必要: LatLngBounds 物件,將結果偏移為由緯度與經度邊界所指定的特定地區。
  • 選擇性: 包含一組地點類型的 AutocompleteFilter,您可以用來將結果限制為一或多種地點類型。 支援下列地點類型:

    • TYPE_FILTER_NONE – 空白篩選器;會傳回所有結果。
    • TYPE_FILTER_GEOCODE – 只傳回地理編碼結果,而不傳回商家。 當指定的位置可能不明確時,可以使用此要求,讓結果更加明確。

    • TYPE_FILTER_ADDRESS – 只傳回具有精確地指的地理編碼結果。 當您知道使用者在尋找完整指定的地址時,便可以使用此要求。

    • TYPE_FILTER_ESTABLISHMENT – 只傳回是商家的地點。

    • TYPE_FILTER_REGIONS – 只傳回符合下列其中一種類型的地點:

      • locality
      • sublocality
      • postal_code
      • country
      • administrative_area_level_1
      • administrative_area_level_2
    • TYPE_FILTER_CITIES – 只傳回符合 localityadministrative_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