オートコンプリート（新）

Autocomplete（新版）は、テキスト検索文字列と検索対象地域を限定する地理的境界を含むリクエストに応じて、場所の候補を返します。予測入力は、入力の完全な単語や部分文字列を照合して、場所の名前や住所、Plus Codes を解決できます。アプリケーションは、ユーザーの入力に合わせて随時クエリを送信し、場所とクエリの候補をリアルタイムで表示することができます。

たとえば、ユーザー入力の一部である「Sicilian piz」を含む文字列を入力として Autocomplete を呼び出し、検索エリアをカリフォルニア州サンフランシスコに限定します。レスポンスには、検索文字列と検索エリアに一致する場所の予測のリスト（「Sicilian Pizza Kitchen」という名前のレストランなど）が含まれます。返される場所の予測は、ユーザーが目的の場所を選択する際に役立つように表示されることを想定しています。Place Details (New) リクエストを行うと、返された場所の予測に関する詳細情報を取得できます。

予測入力（新機能）の機能をアプリに統合する方法は主に 2 つあります。

• プレイス オートコンプリート ウィジェットを追加する: PlaceAutocomplete クラスを介して、すぐに使用できる検索オートコンプリート エクスペリエンスを提供します。このクラスは、ユーザーの入力に応じて予測を表示します。
• 場所の予測をプログラムで取得する: API を直接呼び出して予測を取得し、カスタム ユーザー インターフェースに表示します。

Place Autocomplete ウィジェットを追加する

一貫した場所の予測入力エクスペリエンスをより簡単に提供するには、Place Autocomplete ウィジェットをアプリに追加します。このウィジェットは、ユーザー入力を処理し、場所の予測をユーザーに表示しながら、AutocompletePrediction オブジェクトをアプリに返す専用の全画面インターフェースを提供します。その後、Place Details（新版）リクエストを行って、場所の予測に関する追加情報を取得できます。

プログラムで場所の候補を取得する場合と同様に、Place Autocomplete ウィジェットでは、セッション トークンを使用して、請求処理のために予測入力リクエストをセッションにグループ化できます。setAutocompleteSessionToken() を呼び出してウィジェットのインテントを作成する際に、セッション トークンを渡すことができます。セッション トークンを指定しない場合、ウィジェットによってセッション トークンが作成されます。このトークンには getSessionTokenFromIntent() を呼び出すことでアクセスできます。セッション トークンの使用について詳しくは、セッション トークンについてをご覧ください。

Place Autocomplete ウィジェットをアプリに追加するには:

1. （省略可）セッション トークンを定義します。セッション トークンを指定しない場合、ウィジェットによって自動的に作成されます。

2. 必要なパラメータとセッション トークンを使用して autocompleteIntent を定義します。

3. StartActivityForResult の ActivityResultLauncher を定義します。このランチャーは、オートコンプリート アクティビティから返された結果を処理します。

4. ActivityResultLauncher のコールバックで結果を処理します。これには、AutocompletePrediction と AutocompleteSessionToken の抽出（独自のものを指定していない場合）、エラーの処理、必要に応じて fetchPlace() リクエストを行って場所に関する追加の詳細情報を取得することが含まれます。

5. placeAutocompleteActivityResultLauncher を使用してインテントを起動する

次のサンプルは、Kotlin と Java の両方を使用して Place Autocomplete ウィジェットを追加する方法を示しています。

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

テーマをカスタマイズする

Autocomplete エクスペリエンスをインスタンス化するときに、デフォルトのスタイル属性をオーバーライドするテーマを指定できます。Place Autocomplete コンポーネントの色、タイポグラフィ、スペーシング、枠線、角をカスタマイズできます。デフォルトは PlacesMaterialTheme です。オーバーライドされていないテーマ属性は、デフォルトのスタイルを使用します。

…/res/values/themes.xml でテーマのオーバーライドを定義できます。次に例を示します。

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

オーバーライド スタイルを参照するには、setAutocompleteUiCustomization を呼び出します。

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

プログラムでプレイスの予測を取得する

アプリは、FindAutocompletePredictionsRequest オブジェクトを渡して PlacesClient.findAutocompletePredictions() を呼び出すことで、予測された場所の名前や住所のリストを予測入力 API から取得できます。次の例は、PlacesClient.findAutocompletePredictions() の完全な呼び出しを示しています。

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Autocomplete（新機能）のレスポンス

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

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

• 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 オブジェクトを再度取得できます。Autocomplete のプレイス ID について詳しくは、Place Details（新版）をご覧ください。プレイス ID の概要については、プレイス ID の概要をご覧ください。
• getTypes() は、この場所に関連付けられている場所のタイプのリストを返します。
• getDistanceMeters() は、この場所とリクエストで指定された出発地との間の直線距離をメートル単位で返します。

必須パラメータ

• クエリ

  検索するテキスト文字列。完全な単語や部分文字列、場所の名前、住所、Plus Codes を指定します。Autocomplete (New) サービスは、この文字列と一致する候補を、関連性の高い順に並べて結果として返します。

  クエリ パラメータを設定するには、FindAutocompletePredictionsRequest オブジェクトをビルドするときに setQuery() メソッドを呼び出します。

オプション パラメータ

• 主なタイプ

  レスポンスで返される場所をフィルタリングするために使用される、テーブル A または テーブル B のタイプから最大 5 つのタイプ値のリスト。レスポンスに含めるには、場所が指定された主タイプ値のいずれかと一致する必要があります。

  プレイスに関連付けることができる主タイプは、表 A または表 B のタイプから 1 つのみです。たとえば、プライマリ タイプは "mexican_restaurant" または "steak_house" になります。

  次の場合、リクエストは INVALID_REQUEST エラーで拒否されます。

  • 指定したタイプの数が 5 個より多い。
  • 認識できないタイプが指定されている。

  プライマリ タイプ パラメータを設定するには、FindAutocompletePredictionsRequest オブジェクトをビルドするときに setTypesFilter() メソッドを呼び出します。

• 国

  指定された国の一覧の結果のみを含めます。最大 15 個の ccTLD（「トップレベル ドメイン」）の 2 文字の値のリストとして指定します。省略した場合、レスポンスに制限は適用されません。たとえば、リージョンをドイツとフランスに制限するには:

  locationRestriction と includedRegionCodes の両方を指定すると、結果は 2 つの設定の共通部分に配置されます。

  国パラメータを設定するには、FindAutocompletePredictionsRequest オブジェクトを作成するときに setCountries() メソッドを呼び出します。

• 入力オフセット

  クエリ内のカーソル位置を示す、0 から始まる Unicode 文字オフセット。カーソルの位置は、返される予測に影響する可能性があります。空の場合、デフォルトでクエリの長さになります。

  入力オフセット パラメータを設定するには、FindAutocompletePredictionsRequest オブジェクトをビルドするときに setInputOffset() メソッドを呼び出します。

• 位置情報のバイアスまたは位置情報の制限

  検索エリアを定義するには、位置情報のバイアスまたは位置情報の制限のいずれかを指定します。両方を指定することはできません。位置情報の制限は、結果がその範囲内になければならないリージョンを指定するもの、位置情報のバイアスは、結果がその近くになければならないリージョンを指定するものと考えることができます。主な違いは、位置情報バイアスでは、指定した地域外の結果が返される可能性があることです。

  • 位置バイアス

    検索する領域を指定します。この位置情報は制限ではなくバイアスとして機能するため、指定した範囲外の結果が返されることもあります。

    位置情報のバイアス パラメータを設定するには、FindAutocompletePredictionsRequest オブジェクトをビルドするときに setLocationBias() メソッドを呼び出します。

  • ロケーションの制限

    検索する領域を指定します。指定した範囲外の結果は返されません。

    位置情報の制限パラメータを設定するには、FindAutocompletePredictionsRequest オブジェクトをビルドするときに setLocationRestriction() メソッドを呼び出します。

  位置バイアスまたは位置制限のリージョンを、長方形のビューポートまたは円として指定します。

  • 円は、中心点と半径（メートル単位）で定義されます。半径は 0.0 ～ 50000.0 の範囲で指定する必要があります。デフォルト値は 0.0 です。位置情報の制限では、半径を 0.0 より大きい値に設定する必要があります。それ以外の場合、リクエストは結果を返しません。

  • 長方形は緯度と経度のビューポートで、対角線上の 2 つの low ポイントと high ポイントで表されます。ビューポートは閉じた領域と見なされます。つまり、境界が含まれます。緯度の境界は -90 ～ 90 度（両端を含む）、経度の境界は -180 ～ 180 度（両端を含む）の範囲でなければなりません。

    • low = high の場合、ビューポートはその単一点で構成されます。
    • low.longitude > high.longitude の場合、経度の範囲は反転します（ビューポートが経度 180 度の線を横切ります）。
    • low.longitude = -180 度、high.longitude = 180 度の場合は、ビューポートにすべての経度が含まれます。
    • low.longitude = 180 度、high.longitude = -180 度の場合、経度の範囲は空になります。

    low と high の両方に値を入力する必要があります。また、表されるボックスを空にすることはできません。ビューポートが空の場合、エラーが発生します。

• 出発地

  宛先までの直線距離を計算する起点（getDistanceMeters() を使用してアクセス）。この値を省略すると、直線距離は返されません。緯度と経度の座標として指定する必要があります。

  オリジン パラメータを設定するには、FindAutocompletePredictionsRequest オブジェクトをビルドするときに setOrigin() メソッドを呼び出します。

• 地域コード

  レスポンスのフォーマットに使用される地域コード（住所のフォーマットを含む）。ccTLD（「トップレベル ドメイン」）の 2 文字の値として指定されます。ほとんどの ccTLD コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」（.co.uk）ですが、ISO 3166-1 コードは「gb」（厳密には「グレートブリテンおよび北アイルランド連合王国」のエンティティ用）です。

  無効なリージョン コードを指定すると、API は INVALID_ARGUMENT エラーを返します。このパラメータは、適用される法律に基づいて結果に影響を与える可能性があります。

  地域コード パラメータを設定するには、FindAutocompletePredictionsRequest オブジェクトをビルドするときに setRegionCode() メソッドを呼び出します。

• セッション トークン

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

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

  セッション トークン パラメータを設定するには、FindAutocompletePredictionsRequest オブジェクトをビルドするときに setSessionToken() メソッドを呼び出します。

  詳細については、セッション トークンをご覧ください。

Autocomplete（新機能）の例

位置情報の制限と位置情報のバイアスを使用する

Autocomplete（新規）では、デフォルトで IP バイアスを使用して検索エリアを制御します。IP バイアスを使用すると、API はデバイスの IP アドレスを使用して結果にバイアスをかけます。必要に応じて、位置情報の制限または位置情報のバイアス（両方は不可）を使用して、検索するエリアを指定できます。

位置情報の制限では、検索するエリアを指定します。指定した範囲外の結果は返されません。次の例では、位置情報の制限を使用して、サンフランシスコを中心とする半径 5,000 メートルの円形の位置情報制限にリクエストを制限しています。

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

位置バイアスを使用すると、位置がバイアスとして機能するため、指定したエリア外の結果を含め、指定した位置周辺の結果が返される可能性があります。次の例では、前のリクエストを変更して位置情報バイアスを使用しています。

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

プライマリ タイプを使用する

プライマリ タイプ パラメータを使用すると、表 A と 表 B に記載されている特定タイプの結果のみをリクエストから取得できます。最大 5 つの値の配列を指定できます。省略すると、すべてのタイプが返されます。

次の例では、「Soccer」というクエリ文字列を指定し、primary_types パラメータを使用して、結果を "sporting_goods_store" タイプの施設に制限しています。

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

プライマリ タイプ パラメータを省略すると、"athletic_field" など、望ましくないタイプの施設が結果に含まれることがあります。

送信元を使用する

リクエストに origin パラメータを緯度と経度の座標として指定すると、API は起点から目的地までの直線距離をレスポンスに含めます（getDistanceMeters() を使用してアクセス）。次の例では、起点をサンフランシスコの中心に設定しています。

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Autocomplete（新機能）の最適化

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

概要は次のとおりです。

• 機能的なユーザー インターフェースを最も手早く作成するには、Maps JavaScript API Autocomplete（新版）ウィジェット、Places SDK for Android Autocomplete（新版）ウィジェット、または Places SDK for iOS Autocomplete（新版）ウィジェットを使用します。
• Autocomplete（新規）のデータ フィールドの基本を理解します。
• 位置情報のバイアスと位置情報の制限のフィールドは省略可能ですが、予測入力のパフォーマンスに大きく影響する場合があります。
• エラー処理を使用して、API がエラーを返した場合に、アプリでグレースフル デグラデーションが行われるようにします。
• アプリでは、選択肢がない場合でもユーザーが操作を続行できるようにします。

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

基本的な費用の最適化

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

高度な費用の最適化

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

• ユーザーが選択した場所の緯度/経度または住所のみが必要な場合。その場合は、Geocoding API の方が、Place Details（新版）の呼び出しよりも少ないコストでこの情報を提供できます。
• ユーザーが予測結果を選択するまでの予測入力候補（新）リクエストの回数が、平均 4 回以下の場合。その場合は、リクエストあたりの料金設定の方がセッションあたりの料金設定よりも費用対効果が高くなります。

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

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

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

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

位置情報のバイアス

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

ロケーションの制限

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

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