Autocomplete（新版）は、テキスト検索文字列と検索対象地域を限定する地理的境界を含むリクエストに応じて、場所の候補を返します。予測入力は、入力の完全な単語や部分文字列を照合して、場所の名前や住所、Plus Codes を解決できます。アプリケーションは、ユーザーの入力に合わせて随時クエリを送信し、場所とクエリの候補をリアルタイムで表示することができます。
たとえば、ユーザー入力の一部である「Sicilian piz」を含む文字列を入力として Autocomplete を呼び出し、検索エリアをカリフォルニア州サンフランシスコに限定します。レスポンスには、検索文字列と検索エリアに一致する場所の予測のリスト（「Sicilian Pizza Kitchen」という名前のレストランなど）が含まれます。返される場所の予測は、ユーザーが目的の場所を選択する際に役立つように表示されることを想定しています。Place Details (New) リクエストを行うと、返された場所の予測に関する詳細情報を取得できます。
予測入力（新機能）をアプリに統合する方法は主に 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);
プログラムでプレイスの予測を取得する
アプリは、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)は、場所の説明の全文を返します。これは、プライマリ テキストとセカンダリ テキストの組み合わせです。例: 「Eiffel Tower, Avenue Anatole France, Paris, France」。また、このメソッドでは、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());
})
);