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

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

たとえば、ユーザー入力の一部を含む文字列「Sicilian piz」を入力として使用し、予測入力を呼び出します（検索領域をカリフォルニア州サンフランシスコに限定します）。レスポンスには、検索文字列と検索領域に一致する場所予測のリストが含まれます（「Sicilian Pizza Kitchen」という名前のレストランなど）。

返される場所の候補は、ユーザーが目的の場所を選択しやすいように、ユーザーに表示されるように設計されています。Place Details（新）リクエストを行うと、返された場所予測に関する詳細情報を取得できます。

注: 予測入力（新版）は、Places SDK for Android バージョン 3.5.0 以降で使用できます。詳細については、SDK のバージョンを選択するをご覧ください。

予測入力（新）リクエスト

アプリは 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());
        })
    );

注: Place Autocomplete ウィジェットを使用した呼び出しは、Place Autocomplete（新版）ではなく、常に Place Autocomplete を呼び出します。ウィジェットの呼び出しは初期化メソッドの影響を受けません。

CancellationToken を使用すると、任意のリクエスト クラス（FetchPlaceRequest など）に対するリクエストのキャンセルを試行できます。キャンセルはベスト エフォート ベースで行われます。キャンセル リクエストが発行されると、レスポンスは返されません。キャンセル トークンを発行しても、特定のリクエストがキャンセルされるとは限りません。レスポンスが返されなくても、リクエストに対して課金される場合があります。

予測入力（新）の回答

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

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

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

必須パラメータ

• クエリ

  検索するテキスト文字列。完全な単語と部分文字列、場所の名前、住所、Plus Codes を指定します。予測入力（新）サービスは、この文字列に基づいて一致する候補を返し、認識された関連性に基づいて結果を並べ替えます。

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

省略可能なパラメータ

• 主な種類

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

  場所には、関連付けられているタイプの Table A または Table B から 1 つのプライマリ タイプのみ設定できます。たとえば、プライマリ タイプは "mexican_restaurant" や "steak_house" です。

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

  • 6 つ以上のタイプが指定されている。
  • 認識されないタイプが指定されています。

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

• 国

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

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

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

• 入力オフセット

  クエリ内のカーソル位置を示す、ゼロベースの Unicode 文字オフセット。カーソルの位置は、返される予測の種類に影響します。空の場合、デフォルトでクエリの長さになります。

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

• 地域のバイアスまたは地域の制限

  場所バイアスまたは場所制限を指定して、検索領域を定義できます。ただし、両方は指定できません。ロケーション制限は、結果が含まれるリージョンを指定するものと考えることができ、ロケーション バイアスは、結果が存在する必要があるリージョンを指定するものと考えることができます。主な違いは、場所のバイアスでは、指定した地域外の結果が返される可能性があることです。

  • 場所のバイアス

    検索する領域を指定します。この位置はバイアスとして使用され、制限ではありません。そのため、指定した領域外の結果が返される場合があります。

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

  • 地域の制限

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

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

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

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

  • 長方形は緯度と経度のビューポートであり、対角線上に low と high の 2 つのポイントとして表されます。ビューポートは閉じた領域とみなされ、その境界が含まれます。緯度境界は -90 ～ 90 度の範囲、経度境界は -180 ～ 180 度の範囲にする必要があります。

    注: サポートされているバイアスタイプは、使用している SDK のバージョンによって異なります。CircularBounds は予測入力（新）でのみ使用できます。
    • low = high の場合、ビューポートはその単一点で構成されます。
    • low.longitude > high.longitude の場合、経度の範囲は逆になります（ビューポートは経度線と交差します）。
    • 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() メソッドを呼び出します。

• セッション トークン

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

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

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

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

予測入力（新）の例

地域の制限と地域のバイアスを使用する

予測入力（新版）では、デフォルトで IP バイアスを使用して検索領域を制御します。IP バイアスを設定すると、API はデバイスの IP アドレスを使用して結果にバイアスをかけることができます。必要に応じて、地域制限または場所のバイアス（両方ではなく）を使用して、検索する地域を指定できます。

地域の制限では、検索する地域を指定します。指定した領域外の結果は返されません。次の例では、ロケーション制限を使用して、サンフランシスコを中心とする半径 5,000 m の円形のロケーションにリクエストを制限します。

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());
        })
    );

帰属表示

予測入力（新版）は地図がなくても使用できます。地図を表示する場合は、Google マップを使用する必要があります。地図を使わずに予測入力（新版）サービスからの予測を表示する場合は、検索フィールドや検索結果の横に Google ロゴをインラインで含める必要があります。詳しくは、Google ロゴと帰属情報の表示をご覧ください。