Autocomplete（新版）は、テキスト検索文字列と検索対象地域を制御する地理的境界を含むリクエストに応答して、場所の候補を返します。予測入力は、入力の完全な単語と部分文字列を照合して、場所の名前、住所、Plus Codes を解決できます。アプリケーションは、ユーザーが入力しているときにクエリを送信し、場所とクエリの候補をリアルタイムで提供できます。
たとえば、ユーザー入力の一部である「Sicilian piz」を含む文字列を入力として使用し、検索範囲をカリフォルニア州サンフランシスコに限定して Autocomplete を呼び出します。レスポンスには、検索文字列と検索エリアに一致する場所の予測のリストが含まれます（「Sicilian Pizza Kitchen」というレストランなど）。
返された場所の候補は、ユーザーが目的の場所を選択できるようにユーザーに提示するように設計されています。Place Details (New) リクエストを実行すると、返された場所の予測に関する詳細情報を取得できます。
Autocomplete（新規）リクエスト
アプリは、FindAutocompletePredictionsRequest オブジェクトを渡して PlacesClient.findAutocompletePredictions() を呼び出すことで、予測された地名や住所のリストを 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());
})
);Autocomplete（新規）の回答
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オブジェクトを再度取得できます。Autocomplete のプレイス ID について詳しくは、Place Details (New) をご覧ください。プレイス ID の一般的な情報については、プレイス ID の概要をご覧ください。getTypes()は、この場所に関連付けられている場所タイプのリストを返します。getDistanceMeters()は、この場所とリクエストで指定された起点との間の直線距離（メートル単位）を返します。
必須パラメータ
-
クエリ
検索するテキスト文字列。完全な単語と部分文字列、場所の名前、住所、Plus Codes を指定します。Autocomplete (New) サービスはこの文字列と一致する候補を、関連性の高い順に並べて結果として返します。
クエリ パラメータを設定するには、
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」（技術的には「英国（グレートブリテンおよび北アイルランド連合王国）」のエンティティ）です。
無効なリージョン コードを指定すると、API は
INVALID_ARGUMENTエラーを返します。このパラメータは、適用される法律に基づいて結果に影響する可能性があります。地域コード パラメータを設定するには、
FindAutocompletePredictionsRequestオブジェクトを作成するときにsetRegionCode()メソッドを呼び出します。 -
セッション トークン
セッション トークンは、Autocomplete（新規）の呼び出しを「セッション」として追跡するユーザー作成の文字列です。Autocomplete は、セッション トークンを使用して、ユーザーの予測入力検索のクエリと選択フェーズを、請求処理のために個別のセッションにグループ化します。セッションは、ユーザーが検索語句を入力し始めたときに開始され、ユーザーが場所を選択すると終了します。セッションによっては、複数の検索語句が入力された後に、1 つの場所が選択される場合もあります。セッションが終了すると、トークンは無効になります。アプリはセッションごとに新しいトークンを生成する必要があります。すべてのプログラマティック 自動入力セッションでセッション トークンを使用することをおすすめします（フラグメントを埋め込む場合や、インテントを使用して自動入力を起動する場合、API によって自動的に処理されます）。
Autocomplete は
AutocompleteSessionTokenを使用して各セッションを識別します。アプリは、新しいセッションを開始するたびに新しいセッション トークンを渡し、その後のfetchPlace()の呼び出しで同じトークンと Place ID を渡して、ユーザーが選択した場所の Place Details を取得する必要があります。セッション トークン パラメータを設定するには、
FindAutocompletePredictionsRequestオブジェクトを作成するときにsetSessionToken()メソッドを呼び出します。詳細については、セッション トークンをご覧ください。
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（新規）を使用できます。地図を表示する場合は、Google マップを使用してください。地図を使わずに Autocomplete（新規）サービスからの候補を表示する場合は、検索フィールド/検索結果に Google ロゴをインラインで表示する必要があります。詳しくは、Google のロゴと帰属を表示するをご覧ください。