以上で完了です。

開発を始めるには、デベロッパー ドキュメント をご覧下さい。

Google Places API for Android をアクティベートする

まず初めに Google Developers Console で次の作業を行います。

  1. プロジェクトを作成または選択する
  2. Google Places API for Android をアクティベートする
  3. 適切なキーを作成する
続ける

プレイス オートコンプリート

Google Places API for Android のオートコンプリート サービスでは、ユーザーの検索クエリに対して、プレイスの予測結果を返します。 オートコンプリート サービスは、ユーザーが入力している最中に、お店やサービス、住所、有名なスポットなど、プレイスの候補を返します。

次の方法でアプリにオートコンプリート機能を追加することができます。

オートコンプリート ウィジェットを追加する

オートコンプリート ウィジェットは、組み込みのオートコンプリート機能を備えた検索ダイアログです。 ユーザーが検索キーワードを入力すると、予測されるプレイスのリストが表示され、そこからプレイスを選択できます。 ユーザーがプレイスを選択すると、Place インスタンスが返されます。その後、アプリはこのインスタンスを使用して、選択されたプレイスの詳細を取得できます。

オートコンプリート ウィジェットをアプリに追加する方法として、次の 2 つのオプションがあります。

オプション 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 で PlaceAutocompleteFragment オブジェクトをサポートするには、API レベル 12 以降が必要です。 API レベル 12 より前のアプリを対象としている場合、同じ機能を利用するには SupportPlaceAutocompleteFragment クラスを使用します。 Android v4 Support Library も含める必要があります。

API レベル 12 より前の Android バージョンをサポートするには、次の手順を実行します。

  • メイン アクティビティで FragmentActivity または AppCompatActivity を継承します。
  • PlaceAutocompleteFragment ではなく、SupportPlaceAutocompleteFragment を使用します。
  • getFragmentManager() ではなく、getSupportFragmentManager() を使用します。

オプション 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.
        }
    }
}

オートコンプリートの結果を制限する

特定の地域の結果を優先して返すように、あるいは 1 つまたは複数のプレイスタイプで結果をフィルタリングするようにオートコンプリート ウィジェットを設定することができます。

特定の地域の結果を優先して返す

オートコンプリートで特定の地域の結果を優先して返すには:

  • アプリの 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() を呼び出して使用するフィルタを設定します。

その後、フィルタをフラグメントまたはインテントに渡します。

次のコードサンプルは、PlaceAutocompleteFragmentAutocompleteFilter を設定して、正確な住所が示された結果のみを返すようにフィルタを設定しています。

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 を作成できます。 この UI を作成するには、アプリのプログラムでプレイスの予測結果を取得する必要があります。 アプリで GeoDataApi.getAutocompletePredictions() を呼び出して、次のパラメータを渡すことにより、オートコンプリート サービスによって予測されるプレイスの名前や住所のリストを取得できます。

  • 必須: ユーザーが入力したテキストを含む query 文字列。
  • 必須: LatLngBounds オブジェクト。緯度と経度の範囲で指定した特定のエリアの結果を優先させます。

  • 任意: プレイスタイプのセットを含む AutocompleteFilter。結果を 1 つまたは複数のプレイスタイプに制限する際に使用できます。 サポートされるプレイスタイプは次のとおりです。

    • 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_CITIESlocality または administrative_area_level_3 に一致する結果のみを返します。

プレイスタイプの詳細については、プレイスタイプのガイドと AutocompleteFilter.Builder をご覧ください。

以下の例は、GeoDataApi.getAutocompletePredictions() を簡単に呼び出す方法を示しています。 全体的な例については、サンプルアプリをご覧ください。

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

API は、PendingResult

AutocompletePredictionBuffer を返します。 AutocompletePredictionBuffer には、予測される場所を示す AutocompletePrediction オブジェクトのリストが含まれています。

クエリやフィルタ条件に対応する既知のプレイスがない場合、バッファは空白になります。

注: メモリリークを防ぐため、アプリで必要がなくなったら、AutocompletePredictionBuffer オブジェクトを解放する必要があります。 バッファの処理についての詳細をご確認ください。

予測されるプレイスごとに次のメソッドを呼び出して、プレイス詳細を取得できます。

  • getFullText(CharacterStyle matchStyle) はプレイスの説明の全文を返します。 これはプライマリ テキストとセカンダリ テキストを組み合わせたものです。 例: "Eiffel Tower, Avenue Anatole France, Paris, France"。 また、CharacterStyle を使用すると、説明文の中で検索内容と一致する部分を、指定のスタイルでハイライト表示できます。

CharacterStyle パラメータは省略可能です。 ハイライト表示する必要がない場合は、このパラメータを null に設定してください。

  • getPrimaryText(CharacterStyle matchStyle) はプレイスを説明するメインテキストを返します。 これは通常、プレイスの名前です。 例: "Eiffel Tower", and "123 Pitt Street"。
  • getSecondaryText(CharacterStyle matchStyle) はプレイスの補足説明のテキストを返します。 これは、オートコンプリートの予測結果で 2 行目に表示するテキストなどに適しています。 例: "Avenue Anatole France, Paris, France", and "Sydney, New South Wales"。
  • getPlaceId() は予測されるプレイスのプレイス ID を返します。 プレイス ID は、プレイスを一意に識別するテキスト表記の ID です。この ID を使用して、後で Place オブジェクトを再取得できます。 Google Places API for Android のプレイス ID の詳細については、プレイス ID と詳細をご覧ください。 プレイス ID の一般的な情報については、プレイス ID の概要をご覧ください。

  • getPlaceTypes() はこのプレイスに関連付けられたプレイスタイプのリストを返します。

使用制限

アプリでの帰属表示

  • アプリでプログラムを使ってオートコンプリート サービスを使用する場合は、UI に "Powered by Google" の帰属情報を表示するか、UI を Google ブランドマップ内に表示する必要があります。

  • アプリでオートコンプリート ウィジェットを使用する場合は、追加の対応は必要ありません(必要な帰属情報がデフォルトで表示されます)。

  • ID でプレイスを取得した後、追加のプレイス情報を取得して表示する場合は、サードパーティの帰属表示も必要です。

詳細については、属性をご覧ください。

トラブルシューティング

さまざまなエラーが発生する可能性がありますが、一般的にアプリでよく発生するエラーの主な原因は、設定エラー(誤った API キーが使用された、API キーが正しく設定されていないなど)または割り当てエラー(アプリで割り当てを超過した)です。

割り当ての詳細については、使用制限をご覧ください。

オートコンプリート コントロールの使用時に発生するエラーは、onActivityResult() コールバックで返されます。 結果のステータス メッセージを取得するには、PlaceAutocomplete.getStatus() を呼び出します。

フィードバックを送信...