Autocomplete（新版）は、テキスト検索文字列と検索対象地域を制御する地理的境界を含むリクエストに対して、場所の候補を返します。オートコンプリートは、入力の完全な単語と部分文字列を照合して、場所の名前、住所、Plus Codes を解決できます。アプリケーションは、ユーザーの入力に応じてクエリを送信し、場所とクエリの予測を即座に提供できます。
たとえば、ユーザー入力の一部である「Sicilian piz」を含む文字列を入力として使用し、検索範囲をカリフォルニア州サンフランシスコに限定して Autocomplete を呼び出します。レスポンスには、検索文字列と検索エリアに一致するプレイス予測のリストが含まれます（「Sicilian Pizza Kitchen」というレストランなど）。
返されたプレイスの予測は、目的のプレイスを選択しやすくなるようユーザーに表示するように設計されています。Place Details (New) リクエストを送信すると、返されたプレイス予測の詳細情報を取得できます。
Autocomplete（新規）リクエスト
アプリで PlacesClient.findAutocompletePredictions() を呼び出して FindAutocompletePredictionsRequest オブジェクトを渡すことにより、Autocomplete 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());
})
);
オートコンプリート（新機能）レスポンス
API は Task 内の FindAutocompletePredictionsResponse を返します。FindAutocompletePredictionsResponse には、予測された場所を表す AutocompletePrediction オブジェクトが最大 5 つまで含まれます。クエリやフィルタ条件に対応する既知のプレイスがない場合、リストは空になることがあります。
予測されるプレイスごとに次のメソッドを呼び出して、プレイス詳細を取得できます。
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オブジェクトを再取得できます。オートコンプリートのプレイス ID の詳細については、プレイス情報（新規）をご覧ください。プレイス 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()メソッドを呼び出します。 -
入力オフセット
クエリ内のカーソル位置を示す 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」（厳密には「United Kingdom of Great Britain and Northern Ireland」のエンティティ）です。
無効なリージョン コードを指定すると、API は
INVALID_ARGUMENTエラーを返します。このパラメータは、適用される法律に基づいて結果に影響する可能性があります。地域コード パラメータを設定するには、
FindAutocompletePredictionsRequestオブジェクトを作成するときにsetRegionCode()メソッドを呼び出します。 -
セッション トークン
セッション トークンは、Autocomplete（新規）の呼び出しを「セッション」として追跡するユーザー作成の文字列です。Autocomplete は、セッション トークンを使用して、ユーザーの予測入力検索のクエリと選択フェーズを、請求処理のために個別のセッションにグループ化します。セッションは、ユーザーが検索語句を入力し始めたときに開始され、ユーザーが場所を選択すると終了します。セッションによっては、複数の検索語句が入力された後に、1 つの場所が選択される場合もあります。セッションが終了すると、トークンは無効になります。アプリでは、セッションごとに新しいトークンを生成する必要があります。すべてのプログラマティック 自動入力セッションでセッション トークンを使用することをおすすめします（フラグメントを埋め込む場合や、インテントを使用した自動入力を開始する場合、API によって自動的に処理されます）。
自動入力は
AutocompleteSessionTokenを使用して各セッションを識別します。アプリは、新しいセッションを開始するたびに新しいセッション トークンを渡し、その後のfetchPlace()の呼び出しで同じトークンと Place ID を渡して、ユーザーが選択した場所の Place Details を取得する必要があります。セッション トークン パラメータを設定するには、
FindAutocompletePredictionsRequestオブジェクトを作成するときにsetSessionToken()メソッドを呼び出します。詳細については、セッション トークンをご覧ください。
オートコンプリート（新機能）の例
地域の制限と地域バイアスを使用する
自動入力（新規）では、デフォルトで 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 つの値の配列を指定できます。省略すると、すべてのタイプが返されます。
次の例では、クエリ文字列に「サッカー」を指定し、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());
})
);
帰属表示
オートコンプリート（新規）は、地図がなくても使用できます。地図を表示する場合は、Google マップを使用してください。地図を使わずに Autocomplete（新規）サービスからの候補を表示する場合は、検索フィールド/検索結果に Google ロゴをインラインで表示する必要があります。詳しくは、Google のロゴと帰属を表示するをご覧ください。