オートコンプリート(新)

Autocomplete (new) は、検索領域を制御するテキスト検索文字列と地理的境界を含むリクエストに応答して、場所の予測を返します。オートコンプリートは、入力された完全な単語や部分文字列を照合し、場所の名前、住所、Plus Code を解決できます。アプリケーションは、ユーザーの入力に合わせてクエリを送信し、場所やクエリをその場で予測できます。

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

返される場所予測は、ユーザーが目的の場所を選択できるように、ユーザーに提示するように設計されています。Place Details (New) リクエストを使用すると、返された場所の予測に関する詳細情報を取得できます。

オートコンプリート(新規)リクエスト

アプリで 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 は TaskFindAutocompletePredictionsResponse を返します。FindAutocompletePredictionsResponse には、予測される場所を表す最大 5 つの AutocompletePrediction オブジェクトのリストが含まれます。クエリやフィルタ条件に対応する既知の場所がない場合、リストは空になります。

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

  • getFullText(CharacterStyle) は、場所の説明の全文を返します。これは、プライマリ テキストとセカンダリ テキストを組み合わせたものです。例: 「エッフェル塔, アナトール アベニュー, パリ, フランス」また、この方法では、CharacterStyle を使用して、検索に一致する説明のセクションを、任意のスタイルでハイライト表示できます。CharacterStyle パラメータは省略可能です。ハイライト表示が不要な場合は、null に設定してください。
  • getPrimaryText(CharacterStyle) は、場所について説明するメインテキストを返します。通常は場所の名前です。(例: 「エッフェル塔」、「123 番地」)。
  • getSecondaryText(CharacterStyle) は、場所の説明の補助テキストを返します。これは、オートコンプリート候補を表示するときに 2 行目として使用する場合などに役立ちます。(例: Avenue Anatole France, Paris, FranceSydney, New South Wales)。
  • getPlaceId() は、予測される場所のプレイス ID を返します。プレイス ID は、場所を一意に識別するテキスト表記の ID です。この ID を使用して、後で Place オブジェクトを再度取得できます。Autocomplete のプレイス ID について詳しくは、Place Details(新機能)をご覧ください。プレイス ID に関する一般的な情報については、プレイス ID の概要をご覧ください。
  • getTypes() は、この場所に関連付けられている場所タイプのリストを返します。
  • getDistanceMeters() は、この場所とリクエストで指定された出発地との直線距離をメートル単位で返します。

必須パラメータ

  • クエリ

    検索するテキスト文字列。完全な単語や部分文字列、場所の名前、住所、Plus Code を指定します。Autocomplete (new) サービスは、この文字列と一致する候補を、関連性の高い順に並べて結果を並べ替えます。

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

省略可能なパラメータ

  • メインのタイプ

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

    1 つの場所に指定できる主要なタイプは、Table A または Table B のいずれかのタイプのみです。たとえば、メインのタイプは "mexican_restaurant""steak_house" です。

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

    • 5 個を超えるタイプが指定されています。
    • 認識できないタイプが指定されています。

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

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

    locationRestrictionincludedRegionCodes の両方を指定した場合、結果は 2 つの設定の交差領域に配置されます。

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

  • 入力オフセット

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

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

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

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

    • 場所のバイアス

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

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

    • 地域の制限

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

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

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

    • 円は、中心点と半径(メートル単位)で定義されます。radius は 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 度の場合、経度の範囲は空になります。

      lowhigh の両方を入力する必要があります。表示されるボックスを空にすることはできません。空のビューポートはエラーになります。

  • 出発地

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

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

  • 地域コード

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

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

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

  • セッション トークン

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

    Autocomplete は AutocompleteSessionToken を使用して各セッションを識別します。アプリでは、新しいセッションの開始時に新しいセッション トークンを渡し、その後の fetchPlace() の呼び出しで、同じトークンとプレイス 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());
        })
    );

メインのタイプを使用する

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

次の例では、「Soccer」というクエリ文字列を指定し、primarytypes パラメータを使用して、結果を "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 ロゴとアトリビューションの表示をご覧ください。