Place Autocomplete

欧州経済領域（EEA）のデベロッパー

Android 向け Places SDK の予測入力サービスは、ユーザーの検索クエリに対応して場所の予測を返します。ユーザーが入力すると、オートコンプリート サービスは、お店やサービス、住所、プラスコード、スポットなどの場所の候補を返します。

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

予測入力ウィジェットを追加する

オートコンプリート ウィジェットは、組み込みのオートコンプリート機能を備えた検索ダイアログです。ユーザーが検索語句を入力すると、ウィジェットに候補となる場所のリストが表示され、そこから選択できます。ユーザーが選択を行うと、Place インスタンスが返されます。アプリはこのインスタンスを使用して、選択された場所の詳細情報を取得できます。

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

オプション 1: AutocompleteSupportFragment を埋め込む

アプリに AutocompleteSupportFragment を追加する手順は次のとおりです。

  1. アクティビティの XML レイアウトにフラグメントを追加します。
  2. アクティビティまたはフラグメントにリスナーを追加します。

アクティビティに AutocompleteSupportFragment を追加する

アクティビティに AutocompleteSupportFragment を追加するには、XML レイアウトに新しいフラグメントを追加します。次に例を示します。

<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"
  />
  • デフォルトでは、フラグメントに枠線や背景はありません。視覚的な外観を統一するには、CardView などの別のレイアウト要素内にフラグメントをネストします。
  • オートコンプリート フラグメントを使用しており、onActivityResult をオーバーライドする必要がある場合は、super.onActivityResult を呼び出す必要があります。そうしないと、フラグメントが正しく機能しません。

PlaceSelectionListener をアクティビティに追加する

PlaceSelectionListener は、ユーザーの選択に応じて場所を返す処理を行います。次のコードは、フラグメントへの参照を作成し、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.DISPLAY_NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            binding.autocompleteResult.text = getString(
                R.string.place_selection,
                place.displayName,
                place.id,
                place.formattedAddress
            )
            Log.i(TAG, "Place: ${place.displayName}, ${place.id}")
        }

        override fun onError(status: Status) {
            binding.autocompleteResult.text = getString(R.string.an_error_occurred, status)
            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.
    assert autocompleteFragment != null;
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            binding.autocompleteResult.setText(
                    getString(
                            R.string.place_selection,
                            place.getDisplayName(),
                            place.getId(),
                            place.getFormattedAddress()
                    )
            );
            Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            binding.autocompleteResult.setText(getString(R.string.an_error_occurred, status));
            Log.e(TAG, "An error occurred: " + status);
        }
    });

オプション 2: インテントを使用してオートコンプリート アクティビティを起動する

アプリで別のナビゲーション フローを使用する場合（たとえば、検索フィールドではなくアイコンからオートコンプリート エクスペリエンスをトリガーする場合）、アプリはインテントを使用してオートコンプリートを起動できます。

インテントを使用してオートコンプリート ウィジェットを起動するには、次の手順を実行します。

  1. Autocomplete.IntentBuilder を使用してインテントを作成し、目的の Autocomplete モードを渡します。
  2. インテントを起動し、結果でユーザーが選択した場所の予測を処理するために使用できるアクティビティ結果ランチャー registerForActivityResult を定義します。

オートコンプリート インテントを作成する

次の例では、Autocomplete.IntentBuilder を使用して、予測入力ウィジェットをインテントとして起動するインテントを作成しています。

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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS)

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
        .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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);
    startAutocomplete.launch(intent);

インテントを使用して予測入力ウィジェットを起動する場合、オーバーレイ表示モードまたは全画面表示モードを選択できます。次のスクリーンショットは、それぞれの表示モードを示しています。

オーバーレイ モードで表示される場合、オートコンプリート ウィジェットは通話 UI の上に重ねて表示されます。
図 1: OVERLAY モードのオートコンプリート ウィジェット
全画面モードで表示される場合、オートコンプリート ウィジェットは画面全体を埋めます。
図 2: 全画面モードのオートコンプリート ウィジェット

インテントの結果に対してコールバックを登録する

ユーザーがスポットを選択したときに通知を受け取るには、次の例に示すように、アクティビティを起動し、結果も処理する registerForActivityResult() ランチャーを定義します。ユーザーが予測を選択すると、結果オブジェクトに含まれるインテントで提供されます。インテントは Autocomplete.IntentBuilder によってビルドされているため、Autocomplete.getPlaceFromIntent() メソッドによってプレイス オブジェクトを抽出できます。

Kotlin

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                binding.autocompleteResult.text = getString(
                    R.string.place_selection,
                    place.displayName,
                    place.id,
                    place.formattedAddress)
                Log.i(
                    TAG, "Place: ${place.displayName}, ${place.id}"
                )
            }
        } else if (result.resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
            binding.autocompleteResult.setText(R.string.user_canceled_autocomplete)
            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);
                    binding.autocompleteResult.setText(
                            getString(
                                    R.string.place_selection,
                                    place.getDisplayName(),
                                    place.getId(),
                                    place.getFormattedAddress()
                            )
                    );
                    Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                binding.autocompleteResult.setText(R.string.user_canceled_autocomplete);
                Log.i(TAG, "User canceled autocomplete");
            }
        });

プログラムで場所の予測を取得する

オートコンプリート ウィジェットが提供する UI の代わりに、カスタム検索 UI を作成できます。そのためには、アプリでプレイス予測をプログラムで取得する必要があります。アプリは、PlacesClient.findAutocompletePredictions() を呼び出し、次のパラメータを含む FindAutocompletePredictionsRequest オブジェクトを渡すことで、オートコンプリート API から予測された地名や住所のリストを取得できます。

  • 必須: ユーザーが入力したテキストを含む query 文字列。
  • 推奨: AutocompleteSessionToken。ユーザー検索の検索語句と選択フェーズを、請求処理のために個別のセッションにグループ化します。セッションは、ユーザーが検索語句を入力し始めたときに開始され、ユーザーが場所を選択すると終了します。
  • 推奨: RectangularBounds オブジェクト。緯度と経度の範囲を指定して、結果を指定されたリージョンに制限します。
  • 省略可: 2 文字の国コード（ISO 3166-1 Alpha-2）を 1 つ以上指定します。これは、結果を制限する国を示します。

  • 省略可: TypeFilter。これを使用して、結果を指定した場所のタイプに制限できます。サポートされているスポットタイプは次のとおりです。

    • TypeFilter.GEOCODE - 検索結果として、お店やサービスではなく、ジオコーディングの結果のみを返します。このリクエストは、はっきり特定できない場所を明確にするために使用します。
    • TypeFilter.ADDRESS - 正確な住所を含むオートコンプリートの結果のみを返します。このタイプは、ユーザーが完全な住所を指定して検索することがわかっている場合に使用します。
    • TypeFilter.ESTABLISHMENT - ビジネスの場所のみを返します。

    • TypeFilter.REGIONS - 次のいずれかのタイプに一致する場所のみを返します。

    • LOCALITY

    • SUBLOCALITY

    • POSTAL_CODE

    • COUNTRY

    • ADMINISTRATIVE_AREA_LEVEL_1

    • ADMINISTRATIVE_AREA_LEVEL_2

    • TypeFilter.CITIES - LOCALITY または ADMINISTRATIVE_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.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            val builder = StringBuilder()
            for (prediction in response.autocompletePredictions) {
                builder.append(prediction.getPrimaryText(null).toString()).append("\n")
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
            binding.autocompleteResult.text = builder.toString()
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
                binding.autocompleteResult.text = getString(R.string.place_not_found, exception.message)
            }
        }

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(List.of(PlaceTypes.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        StringBuilder builder = new StringBuilder();
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            builder.append(prediction.getPrimaryText(null).toString()).append("\n");
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
        binding.autocompleteResult.setText(builder.toString());
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException apiException) {
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
            binding.autocompleteResult.setText(getString(R.string.place_not_found, apiException.getMessage()));
        }
    });

API は Task で FindAutocompletePredictionsResponse を返します。FindAutocompletePredictionsResponse には、予測された場所を表す AutocompletePrediction オブジェクトのリストが含まれます。クエリとフィルタ条件に対応する既知の場所がない場合、リストは空になることがあります。

予測された場所ごとに、次のメソッドを呼び出して場所の詳細を取得できます。

  • getFullText(CharacterStyle) は、場所の説明の全文を返します。これは、プライマリ テキストとセカンダリ テキストの組み合わせです。例: 「エッフェル塔、アナトール フランス通り、パリ、フランス」。また、このメソッドでは、CharacterStyle を使用して、検索に一致する説明のセクションを任意のスタイルでハイライト表示できます。CharacterStyle パラメータは省略可能です。ハイライト表示が必要ない場合は、null に設定します。
  • getPrimaryText(CharacterStyle) 場所の説明のメインテキストを返します。通常、これは場所の名前です。例: 「エッフェル塔」、「ピット ストリート 123 番地」。
  • getSecondaryText(CharacterStyle) は、場所の説明の補助テキストを返します。これは、たとえばオートコンプリートの予測を表示する際の 2 行目として使用するのに便利です。例: 「Avenue Anatole France, Paris, France」、「Sydney, New South Wales」。
  • getPlaceId() は、予測された場所のプレイス ID を返します。プレイス ID は、場所を一意に識別するテキスト表記の ID です。この ID を使用して、後で Place オブジェクトを再度取得できます。Places SDK for Android のプレイス ID について詳しくは、プレイスの詳細をご覧ください。プレイス ID の概要については、プレイス ID の概要をご覧ください。
  • getPlaceTypes() は、この場所に関連付けられている場所のタイプのリストを返します。
  • getDistanceMeters() は、この場所とリクエストで指定された出発地との間の直線距離をメートル単位で返します。

セッション トークン

セッション トークンは、予測入力検索でのユーザーのクエリと選択フェーズを、請求処理のために個別のセッションにグループ化します。セッションは、ユーザーが検索語句を入力し始めたときに開始され、ユーザーが場所を選択すると終了します。セッションによっては、複数の検索語句が入力された後に、1 つの場所が選択される場合もあります。セッションが終了すると、トークンは無効になります。アプリでは、セッションごとに新しいトークンを生成する必要があります。すべてのプログラムによる予測入力セッションでセッション トークンを使用することをおすすめします（フラグメントを埋め込む場合や、インテントを使用して予測入力を起動する場合、API が自動的に処理します）。

Places SDK for Android は、AutocompleteSessionToken を使用して各セッションを識別します。アプリは、新しいセッションを開始するたびに新しいセッション トークンを渡し、その後の fetchPlace() の呼び出しで、同じトークンと Place ID を渡して、ユーザーが選択した場所の Place Details を取得する必要があります。

セッション トークンの詳細

予測入力候補を制限する

予測入力の結果を特定の地理的地域に制限したり、結果を 1 つ以上の場所のタイプまたは最大 5 つの国にフィルタしたりできます。これらの制約は、オートコンプリート アクティビティ、AutocompleteSupportFragment、プログラムによるオートコンプリート API に適用できます。

結果を制限するには、次の操作を行います。

  • 定義された地域内の結果を優先するには、setLocationBias() を呼び出します（定義された地域外の結果が返されることもあります）。
  • 定義された地域内の結果のみを表示するには、setLocationRestriction() を呼び出します（定義された地域内の結果のみが返されます）。
  • 特定の場所のタイプに準拠する結果のみを返すには、setTypesFilter() を呼び出します（たとえば、TypeFilter.ADDRESS を指定すると、正確な住所を含む結果のみが返されます）。
  • 指定した 5 つまでの国での結果のみを返すには、setCountries() を呼び出します。国は、ISO 3166-1 Alpha-2 に準拠した 2 文字の国コードで指定してください。

特定のリージョンを優先するよう結果にバイアスを設定する

特定の地域を優先するよう予測入力の結果にバイアスを設定するには、setLocationBias() を呼び出し、RectangularBounds を渡します。次のコード例は、フラグメント インスタンスで setLocationBias() を呼び出して、オーストラリアのシドニーの地域に予測入力候補をバイアスする方法を示しています。

Kotlin

        autocompleteFragment.setLocationBias(bounds)

Java

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

結果を特定の地域に制限する

オートコンプリートの結果を特定の地域に制限するには、setLocationRestriction() を呼び出し、RectangularBounds を渡します。次のコード例は、フラグメント インスタンスで setLocationRestriction() を呼び出して、オーストラリアのシドニーの地域に自動補完候補をバイアスする方法を示しています。

Kotlin

        autocompleteFragment.setLocationRestriction(bounds)

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 値を最大 5 つ指定します。型値は PlaceTypes の定数で定義されます。

  • setTypesFilter() を呼び出し、プレイスタイプの表 3 に示されているタイプ コレクションを指定します。コレクションの値は、PlaceTypes の定数で定義されます。

    リクエストでは、表 3 のタイプのうち、1 つのみが許可されます。表 3 の値を指定する場合、表 1 または表 2 の値は指定できません。その場合、エラーが発生します。

次のコード例では、AutocompleteSupportFragment で setTypesFilter() を呼び出し、複数の型値を指定しています。

Kotlin

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

Java

    autocompleteFragment.setTypesFilter(List.of("landmark", "restaurant", "store"));

次のコード例は、AutocompleteSupportFragment で setTypesFilter() を呼び出し、型コレクションを指定して正確な住所の結果のみを返すフィルタを設定する方法を示しています。

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

Java

    autocompleteFragment.setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT));

次のコード例は、IntentBuilder で setTypesFilter() を呼び出し、型コレクションを指定して、正確な住所の結果のみを返すフィルタを設定する方法を示しています。

Kotlin

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
        .build(this)

Java

    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);

国で検索結果をフィルタする

予測入力の結果を最大 5 か国に絞り込むには、setCountries() を呼び出して国コードを設定します。次に、フィルタをフラグメントまたはインテントに渡します。国は、ISO 3166-1 Alpha-2 に準拠した 2 文字の国コードで指定してください。

次のコード例は、AutocompleteSupportFragment で setCountries() を呼び出し、指定した国での結果のみを返すフィルタを設定する方法を示しています。

Kotlin

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

Java

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

使用量上限

Places SDK for Android を含む Places API の使用量について、1 日あたりのリクエスト数（QPD）の上限は撤廃されました。ただし、次の使用制限は引き続き適用されます。

  • レート制限は 6,000 QPM（1 分あたりのリクエスト回数）です。これは、同じプロジェクトの認証情報を使用するすべてのアプリケーションのクライアント側リクエストとサーバー側リクエストの合計として計算されます。

アプリに属性を表示する

  • アプリでオートコンプリート サービスをプログラムで使用する場合、UI に「Powered by Google」という帰属情報を表示するか、Google ブランドの地図内に表示する必要があります。
  • アプリでオートコンプリート ウィジェットを使用している場合は、追加の操作は必要ありません（必要な帰属表示はデフォルトで表示されます）。
  • ID でプレイスを取得した後に追加のプレイス情報を取得して表示する場合は、サードパーティ帰属も表示する必要があります。

詳しくは、帰属に関するドキュメントをご覧ください。

Place Autocomplete（従来版）の最適化

このセクションでは、Place Autocomplete（以前のバージョン）サービスを最大限に活用するためのヒントを紹介します。

概要は次のとおりです。

費用の最適化に関するヒント

基本的な費用の最適化

Place Autocomplete（従来版）サービスの使用コストを最適化するには、Place Details（従来版）と Place Autocomplete（従来版）ウィジェットのフィールド マスクを使用して、必要な Place Autocomplete（従来版）のデータ フィールドのみを返すように設定します。

高度な費用の最適化

SKU: Autocomplete - Per Request の料金設定を利用し、Place Details（Legacy）の代わりに選択された場所に関する Geocoding API の結果をリクエストするためには、Place Autocomplete（Legacy）のプログラマティック実装を行うことをおすすめします。次の両方に該当する場合は、リクエストあたりの料金設定と Geocoding API を組み合わせた方が、セッションあたり（セッション ベース）の料金設定よりも費用対効果が高くなります。

  • ユーザーが選択した場所の緯度/経度または住所のみが必要な場合。その場合は、Geocoding API の方が、Place Details（レガシー）の呼び出しよりも少ないコストでこの情報を提供できます。
  • ユーザーが予測結果を選択するまでの Place Autocomplete（レガシー）予測入力候補リクエストの回数が、平均 4 回以下の場合。その場合は、リクエストあたりの料金設定の方がセッションあたりの料金設定よりも費用対効果が高くなります。
ニーズに合った Place Autocomplete（レガシー）実装を選ぶ際は、次の質問に対する答えを考え、それに対応するタブを選択するとヒントが表示されます。

アプリケーションで、選択された予測結果の住所と緯度 / 経度以外の情報が必要ですか？

はい。その他の情報も必要です

セッション ベースの Place Autocomplete（従来版）と Place Details（従来版）を併用します。
アプリケーションで、場所の名前、ビジネス ステータス、営業時間などの Place Details（以前のバージョン）が必要なため、Place Autocomplete（以前のバージョン）の実装では、セッション トークン（プログラムまたは JavaScript、Android、iOS ウィジェットに組み込まれている）をセッションごとに使用する必要があります。また、リクエストする場所のデータ フィールドに応じて、該当する Places Data SKU も使用する必要があります。1

ウィジェット実装
セッション管理が JavaScript、Android、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Place Autocomplete（Legacy）リクエストと Place Details（Legacy）リクエストの両方が含まれます。必要な Place Autocomplete（Legacy）データ フィールドのみをリクエストするように、必ず fields パラメータを指定してください。

プログラマティック実装
Place Autocomplete（レガシー）リクエストでセッション トークンを使用します。選択された予測結果に関する Place Details（Legacy）をリクエストする際は、次のパラメータを含めます。

  1. Place Autocomplete（従来版）レスポンスのプレイス ID
  2. Place Autocomplete（レガシー）リクエストで使用されるセッション トークン
  3. 必要な Place Autocomplete（従来版）のデータ フィールドを指定する fields パラメータ

いいえ。住所と場所のみが必要です

Place Autocomplete（レガシー）の使用時のパフォーマンスによっては、アプリケーションで Place Details（レガシー）を使用するよりも、Geocoding API を使用した方が費用対効果が高くなる場合があります。アプリケーションの Place Autocomplete（レガシー）の効率は、ユーザーの入力内容や、アプリケーションが使用される場所、パフォーマンス最適化のベスト プラクティスが導入されているかどうかによって変わります。

次の質問に答えるためには、ユーザーがアプリケーション内で Place Autocomplete（従来版）の予測を選択するまでに、平均でどのくらいの文字数を入力するのかを分析する必要があります。

ユーザーが Place Autocomplete（従来版）の予測を選択するまでに実行されるリクエスト数は、平均で 4 回以下ですか？

○

セッション トークンを使用せずにプログラムによって Place Autocomplete（従来版）を実装し、選択された場所の予測で Geocoding API を呼び出します。
Geocoding API は、住所と緯度/経度の座標を提供します。Autocomplete - Per Request のリクエスト 4 件と、選択された場所予測に関する Geocoding API の呼び出しを合わせた料金は、Place Autocomplete（Legacy）のセッションあたりの料金よりも安くなります。1

パフォーマンスに関するベスト プラクティスを導入し、できるだけ少ない入力文字数でユーザーが求める情報を提供できるようすることをおすすめします。

いいえ

セッション ベースの Place Autocomplete（従来版）と Place Details（従来版）を併用します。
ユーザーが Place Autocomplete（Legacy）の予測を選択するまでに行うリクエストの平均数が、セッション単位の料金設定の費用を超えるため、Place Autocomplete（Legacy）の実装では、Place Autocomplete（Legacy）リクエストと関連する Place Details（Legacy）リクエストの両方で、セッション単位のセッション トークンを使用する必要があります。1

ウィジェット実装
セッション管理が JavaScript、Android、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Place Autocomplete（レガシー）リクエストと Place Details（レガシー）リクエストの両方が含まれます。必要なフィールドのみをリクエストするように、必ず fields パラメータを指定してください。

プログラマティック実装
Place Autocomplete（レガシー）リクエストでセッション トークンを使用します。選択された予測結果に関する Place Details（Legacy）をリクエストする際は、次のパラメータを含めます。

  1. Place Autocomplete（従来版）レスポンスのプレイス ID
  2. Place Autocomplete（従来版）リクエストで使用されるセッション トークン
  3. 住所やジオメトリなどの基本データ フィールドを指定する fields パラメータ

Place Autocomplete（Legacy）リクエストを遅らせることを検討する
ユーザーが最初の 3 ～ 4 文字を入力するまで Place Autocomplete（Legacy）リクエストを遅らせて、アプリケーションでのリクエスト数を減らすこともできます。たとえば、ユーザーが 3 文字を入力した後に、入力された文字ごとに Place Autocomplete（Legacy）リクエストを行う場合、ユーザーが 7 文字を入力して、予測を選択し、それに対して Geocoding API リクエストを 1 回行うと、合計料金は Place Autocomplete（Legacy）Per Request 4 回分 + Geocoding になります。1

リクエストを遅らせることで、プログラマティック リクエストの回数を平均 4 回以下に抑えられる場合は、高パフォーマンスで Place Autocomplete（レガシー）と Geocoding API を併用する実装に関するガイダンスをご覧ください。なお、リクエストを遅らせると、1 文字入力するたびに予測が表示されはずと考えているユーザーには、遅延と受けとられる場合もあります。

パフォーマンスに関するベスト プラクティスを導入し、できるだけ少ない入力文字数でユーザーが求める情報を提供できるようすることをおすすめします。

  1. 費用については、Google Maps Platform の料金リストをご覧ください。

パフォーマンスに関するベスト プラクティス

Place Autocomplete（レガシー）のパフォーマンスを最適化するためのガイドラインは次のとおりです。

  • Place Autocomplete（従来版）実装に、国別のポリシー、場所のバイアス、言語設定（プログラマティック実装の場合）を追加します。ウィジェットはユーザーのブラウザやモバイル デバイスから言語設定を選択するため、ウィジェットでは言語設定は不要です。
  • Place Autocomplete（従来版）が地図に関連付けられている場合は、地図のビューポートを基準に場所にバイアスをかけることができます。
  • ユーザーが Place Autocomplete（従来版）の予測入力候補を選択しなかった場合は（通常は目的の住所が候補に挙がらなかったことが原因）、ユーザーの元の入力内容を再利用して、より関連性の高い結果を取得できます。
    • ユーザーが住所情報のみを入力することが予想される場合は、Geocoding API の呼び出しで、ユーザーの元の入力内容を再利用します。
    • ユーザーが特定の場所に関する検索語句（名前や住所）を入力することが予想される場合は、Place Details（Legacy）リクエストを使用します。特定の地域の結果のみが求められる場合は、場所のバイアスを使用します。
    Geocoding API へのフォールバックが最適となるその他のシナリオは次のとおりです。
    • 建物内の特定のユニットやアパートの住所など、サブプレミス住所を入力するユーザー。たとえば、チェコ語の住所「Stroupežnického 3191/17, Praha」では、Place Autocomplete（従来版）で部分的な予測が生成されます。
    • ユーザーがニューヨークの「23-30 29th St, Queens」や、ハワイのカウアイ島の「47-380 Kamehameha Hwy, Kaneohe」など、道路区間のプレフィックスを入力する場合。

位置情報のバイアス

location パラメータと radius パラメータを渡すことで、バイアスを設定し、指定した範囲内の結果を優先します。これにより、定義されたエリア内の結果を優先的に表示するよう Place Autocomplete（従来版）に指示します。指定した範囲外の結果が返されることもあります。components パラメータを使用すると、指定した国内の場所のみを表示するように結果をフィルタできます。

ロケーションの制限

locationRestriction パラメータを渡すことで、結果を指定したエリアに制限します。

strictbounds パラメータを追加して、location パラメータと radius パラメータで定義された地域に結果を制限することもできます。これにより、Place Autocomplete（従来版）は、その地域内の結果のみを返すようになります。

トラブルシューティング

さまざまなエラーが発生する可能性がありますが、アプリで発生するエラーのほとんどは、通常、構成エラー（間違った API キーが使用された、API キーが正しく構成されていないなど）または割り当てエラー（アプリが割り当てを超過した）が原因です。割り当ての詳細については、使用量上限をご覧ください。

予測入力コントロールの使用中に発生したエラーは、onActivityResult() コールバックで返されます。結果のステータス メッセージを取得するには、Autocomplete.getStatus() を呼び出します。