Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

プラットフォームを選択: Android iOS JavaScript ウェブサービス

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

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

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

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

Place Autocomplete ウィジェットを追加する: PlaceAutocomplete クラスを使用して、ユーザーが入力した内容に基づいて予測を表示する、すぐに使用可能な検索予測入力機能を提供します。
プログラムで場所の予測を取得する: API を直接呼び出して予測を取得し、カスタムユーザーインターフェースに表示します。

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

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

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

（省略可）セッショントークンを定義します。セッショントークンを指定しない場合、ウィジェットによって自動的に作成されます。
必要なパラメータとセッショントークンを使用して autocompleteIntent を定義します。
StartActivityForResult の ActivityResultLauncher を定義します。このランチャーは、予測入力アクティビティから返された結果を処理します。
ActivityResultLauncher のコールバックで結果を処理します。これには、AutocompletePrediction と AutocompleteSessionToken（独自のものを指定していない場合）の抽出、エラーの処理、必要に応じて fetchPlace() リクエストを送信して場所に関する詳細情報の取得が含まれます。
placeAutocompleteActivityResultLauncher を使用してインテントを起動する

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

Kotlin

// 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)

Java

// 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);

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

予測入力エクスペリエンスをインスタンス化する際に、デフォルトのスタイル属性をオーバーライドするテーマを指定できます。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);

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

アプリは、PlacesClient.findAutocompletePredictions() を呼び出して FindAutocompletePredictionsRequest オブジェクトを渡すことで、予測入力 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());
        })
    );

注: PlacesClient の初期化について詳しくは、Places API クライアントを初期化するをご覧ください。

Autocomplete（新版）のレスポンス

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

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

getFullText(CharacterStyle) は、場所の説明の全文を返します。これは、プライマリテキストとセカンダリテキストの組み合わせです。例: 「Eiffel Tower, Avenue Anatole France, Paris, France」。また、このメソッドでは、CharacterStyle を使用して、検索に一致する説明のセクションを任意のスタイルでハイライト表示できます。CharacterStyle パラメータは省略可能です。ハイライト表示が不要な場合は、null に設定します。
getPrimaryText(CharacterStyle) は、場所を説明するメインテキストを返します。通常、これは場所の名前です。例: 「エッフェル塔」、「123 Pitt Street」
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（新版）サービスは、この文字列と一致する候補を、関連性の高い順に並べて結果として返します。

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

オプションパラメータ

メインのタイプ

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

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

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

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

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

国

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

locationRestriction と includedRegionCodes の両方を指定すると、2 つの設定の交差領域に結果が配置されます。

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

入力オフセット

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

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

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

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

位置バイアス

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

位置情報のバイアスパラメータを設定するには、FindAutocompletePredictionsRequest オブジェクトの作成時に setLocationBias() メソッドを呼び出します。
ロケーションの制限

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

地域制限パラメータを設定するには、FindAutocompletePredictionsRequest オブジェクトの作成時に setLocationRestriction() メソッドを呼び出します。

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

円は、中心点と半径（メートル単位）で定義されます。半径は 0.0 ～ 50000.0（指定した値を含む）の範囲で指定してください。デフォルト値は 0.0 です。地域制限の場合、半径を 0.0 より大きい値に設定する必要があります。それ以外の場合、リクエストは結果を返しません。
長方形は、対角線上にある 2 つの low ポイントと high ポイントで表される、緯度と経度のビューポートです。ビューポートは閉じた領域と見なされます。つまり、境界が含まれます。緯度の範囲は -90 ～ 90 度、経度の範囲は -180 ～ 180 度にする必要があります。

注: サポートされているバイアスタイプは、使用している SDK のバージョンによって異なります。CircularBounds は Autocomplete（新版）でのみ利用できます。
- low = high の場合、ビューポートはその単一のポイントで構成されます。
- low.longitude > high.longitude の場合、経度の範囲は反転します（ビューポートは経度 180 度の線をまたぎます）。
- low.longitude = -180 度、high.longitude = 180 度の場合、ビューポートにはすべての経度が含まれます。
- low.longitude = 180 度、high.longitude = -180 度の場合、経度範囲は空になります。
low と high の両方に値を入力する必要があります。また、表されるボックスを空にすることはできません。ビューポートが空の場合、エラーが発生します。

出発地

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

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

地域コード

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

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

リージョンコードパラメータを設定するには、FindAutocompletePredictionsRequest オブジェクトの作成時に setRegionCode() メソッドを呼び出します。

セッショントークン

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

予測入力では、AutocompleteSessionToken を使用して各セッションを識別します。アプリは、新しいセッションを開始するたびに新しいセッショントークンを渡し、その後、fetchPlace() の呼び出しで同じトークンとプレイス ID を渡して、ユーザーが選択した場所の 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());
        })
    );

メインタイプを使用する

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

次の例では、クエリ文字列に「Soccer」を指定し、プライマリタイプパラメータを使用して、結果を "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（新版）リクエストの平均数	おすすめの実装方法
住所と位置以外の Place Details（場所の名前、ビジネスのステータス、営業時間など）	その他の数字	セッションベースの Autocomplete（新版）と Place Details（新版）
選択された予測結果の住所と緯度 / 経度のみ	4 以下	リクエストごとの Autocomplete（新版）と Geocoding API
選択された予測結果の住所と緯度 / 経度のみ	4 回以上	住所のみのアプリケーション向けのセッションベースの Autocomplete（新版）

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

表のリクエストの平均数を確認するには、ユーザーがアプリケーション内で Autocomplete（新版）の予測を選択するまでに、平均でどのくらいの文字数を入力するのかを分析します。

セッションベースの Autocomplete（新版）と Place Details（新版）

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

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

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

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

Geocoding API を使用したリクエストごとの Autocomplete（新版）

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

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

住所のみのアプリケーション向けのセッションベースの Autocomplete（新版）

セッションベースの Autocomplete（新版）と Place Details（新版）を併用します。
ユーザーが Autocomplete（新版）の予測を選択するまでに予想されるリクエストの平均数が、セッションあたりの料金を上回るため、Autocomplete（新版）の実装では、Autocomplete（新版）リクエストと関連する Place Details（新版）リクエストの両方にセッショントークンを使用する必要があります。セッションごと。 ¹

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

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

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

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

費用については、Google Maps Platform の料金表をご覧ください。

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

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

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

位置情報のバイアス

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

警告: radius が指定されていない場合、location パラメータは無視されます。

検索エリアが広い場合、通常、施設の結果は検索結果に表示されるほど上位にランク付けされません。施設とジオコードが混在する結果に施設を表示する場合は、より小さい半径を指定できます。または、types=establishment を使用して、結果を施設のみに制限します。

ロケーションの制限

locationRestriction パラメータを渡して、結果を特定のエリアに制限します。

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

オートコンプリート（新） コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

Kotlin

Java

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

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

Autocomplete（新版）のレスポンス

必須パラメータ

クエリ

オプション パラメータ

メインのタイプ

国

入力オフセット

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

位置バイアス

ロケーションの制限

出発地

地域コード

セッション トークン

Autocomplete（新版）の例

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

メインタイプを使用する

オリジンを使用

Autocomplete（新版）の最適化

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

基本的な費用の最適化

高度な費用の最適化

セッション ベースの Autocomplete（新版）と Place Details（新版）

Geocoding API を使用したリクエストごとの Autocomplete（新版）

住所のみのアプリケーション向けのセッション ベースの Autocomplete（新版）

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

位置情報のバイアス

ロケーションの制限

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

オプションパラメータ

セッショントークン

セッションベースの Autocomplete（新版）と Place Details（新版）

住所のみのアプリケーション向けのセッションベースの Autocomplete（新版）

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