Place Autocomplete

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。
プラットフォームを選択: Android iOS JavaScript ウェブサービス

Places SDK for Android のオートコンプリート サービスは、ユーザーの検索クエリに応じて場所の予測を返します。ユーザーがオートコンプリートを行うと、オートコンプリート サービスによって、ビジネス、住所、Plus Codes、スポットなどの場所の候補が返されます。

次の方法でアプリにオートコンプリート機能を追加することができます。

オートコンプリート ウィジェットを追加する

オートコンプリート ウィジェットは、組み込みのオートコンプリート機能を備えた検索ダイアログです。ユーザーが検索語句を入力すると、予測された場所のリストがウィジェットに表示されます。ユーザーが選択を行うと、Place インスタンスが返されます。アプリは、これを使用して、選択された場所に関する詳細情報を取得できます。

オートコンプリート ウィジェットをアプリに追加する方法として、次の 2 つのオプションがあります。

オプション 1: AutocompleteSupportFragment を埋め込む

アプリに AutocompleteSupportFragment を追加する手順は次のとおりです。

  1. アクティビティの XML レイアウトにフラグメントを追加します。
  2. アクティビティまたはフラグメントにリスナーを追加します。

AutocompleteSupportFragment をアクティビティに追加する

アクティビティに AutocompleteSupportFragment を追加するには、XML レイアウトに新しいフラグメントを追加します。例:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />
  • デフォルトでは、フラグメントには枠線や背景はありません。一貫した外観を実現するには、CardView などの別のレイアウト要素内にフラグメントをネストします。
  • Autocomplete フラグメントを使用していて、onActivityResult をオーバーライドする必要がある場合は、super.onActivityResult を呼び出す必要があります。そうしないと、フラグメントは正しく機能しません。

PlaceSelectionListener をアクティビティに追加する

PlaceSelectionListener は、ユーザーの選択に応じて場所を返す処理を行います。次のコードは、フラグメントへの参照を作成し、AutocompleteSupportFragment にリスナーを追加する方法を示しています。

Java


    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
        getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

Kotlin


    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
            as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

オプション 2: インテントを使用してオートコンプリート アクティビティを起動する

アプリで別のナビゲーション フローを使用する(たとえば、検索フィールドではなくアイコンからオートコンプリートをトリガーする)場合は、インテントを使用してオートコンプリートを起動できます。

インテントを使用してオートコンプリート ウィジェットを起動するには、次の手順を実行します。

  1. Autocomplete.IntentBuilder を使用してインテントを作成し、目的の Autocomplete モードを渡します。インテントは startActivityForResult を呼び出し、インテントを識別するリクエスト コードを渡す必要があります。
  2. onActivityResult コールバックをオーバーライドして、選択した場所を受け取ります。

オートコンプリート インテントを作成する

以下の例は、Autocomplete.IntentBuilder を使用して、インテントとしてオートコンプリート ウィジェットを起動するインテントを作成する方法を示しています。

Java


    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

インテントを使用してオートコンプリート ウィジェットを起動する場合は、オーバーレイ モードまたは全画面モードを選択できます。次のスクリーンショットは、それぞれ表示モードを示しています。

オーバーレイ モードでは、オートコンプリート ウィジェットは呼び出し元の UI に重ねて表示されます。
図 1: オーバーレイ モードのオートコンプリート ウィジェット
オートコンプリート モードでは、オートコンプリート ウィジェットは画面全体に表示されます。
図 2: 全画面モードのオートコンプリート ウィジェット

onActivityResult コールバックをオーバーライドする

ユーザーが場所を選択したときに通知を受け取るには、次の例に示すように、アプリでアクティビティの onActivityResult() をオーバーライドして、インテントに渡したリクエスト コードを確認する必要があります。

Java


@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

Kotlin


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

プログラムによる場所予測の取得

オートコンプリート ウィジェットで提供される UI の代わりに、カスタム検索 UI を作成できます。これを行うには、アプリでプログラムによって場所の予測を取得する必要があります。アプリでは、PlacesClient.findAutocompletePredictions() を呼び出して次のパラメータの FindAutocompletePredictionsRequest オブジェクトを渡すことで、オートコンプリート API から予測される場所の名前や住所のリストを取得できます。

  • 必須: ユーザーが入力したテキストを含む query 文字列。
  • 推奨: AutocompleteSessionToken。ユーザー検索のクエリと選択のフェーズを、請求処理のために個別のセッションにグループ化します。セッションは、ユーザーが検索語句を入力し始めたときに開始され、ユーザーが場所を選択すると終了します。
  • 推奨: RectangularBounds オブジェクト。緯度と経度の境界を指定して、指定したリージョンに結果を制限します
  • 省略可: 検索結果を制限する国を示す、2 文字の国コード(ISO 3166-1 Alpha-2)を 1 つ以上指定します。
  • 省略可: TypeFilter。結果を特定の場所タイプに制限できます。サポートされる場所のタイプは次のとおりです。

    • TypeFilter.GEOCODE - ビジネスではなく、ジオコーディングの結果のみを返します。このリクエストを使用すると、特定の場所が不確定な場合に結果を明確にできます。
    • TypeFilter.ADDRESS - 正確な住所を含むオートコンプリートの結果のみを返します。ユーザーが完全な住所を指定して検索することがわかっている場合は、このタイプを使用します。
    • TypeFilter.ESTABLISHMENT - ビジネスの場所のみを返します。
    • TypeFilter.REGIONS - 次のいずれかのタイプに一致する場所のみを返します。

      • LOCALITY
      • SUBLOCALITY
      • POSTAL_CODE
      • COUNTRY
      • ADMINISTRATIVE_AREA_LEVEL_1
      • ADMINISTRATIVE_AREA_LEVEL_2
    • TypeFilter.CITIES - LOCALITY または ADMINISTRATIVE_AREA_LEVEL_3 に一致する結果のみを返します。

  • 省略可: リクエストの出発地のロケーションを指定する LatLngsetOrigin() を呼び出すと、レスポンスのオートコンプリート予測ごとに、指定した起点からの距離(distanceMeters)がサービスで返されます。

場所のタイプについて詳しくは、場所のタイプに関するガイドをご覧ください。

以下の例は、PlacesClient.findAutocompletePredictions() の完全な呼び出しを示しています。

Java


    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
        // Call either setLocationBias() OR setLocationRestriction().
        .setLocationBias(bounds)
        //.setLocationRestriction(bounds)
        .setOrigin(new LatLng(-33.8749937,151.2041382))
        .setCountries("AU", "NZ")
        .setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()))
        .setSessionToken(token)
        .setQuery(query)
        .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

Kotlin


    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: " + exception.statusCode)
            }
        }

      

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

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

  • 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 オブジェクトを再度取得できます。Places SDK for Android の場所 ID について詳しくは、Place Details をご覧ください。場所 ID の概要については、場所 ID の概要をご覧ください。
  • getPlaceTypes() は、この場所に関連付けられた場所のタイプのリストを返します。
  • getDistanceMeters() は、この場所とリクエストで指定された出発地との間の直線距離をメートル単位で返します。

セッション トークン

セッション トークンは、オートコンプリート検索でのユーザーの検索語句と選択フェーズを、請求処理のために個別のセッションにグループ化します。セッションは、ユーザーが検索語句を入力し始めたときに開始され、ユーザーが場所を選択すると終了します。各セッションには、複数のクエリと、それに続く 1 つの場所の選択が含まれます。セッションが終了すると、トークンは無効になります。アプリはセッションごとに新しいトークンを生成する必要があります。すべてのプログラマティック オートコンプリート セッションでセッション トークンを使用することをおすすめします(フラグメントを埋め込む場合や、インテントを使用してオートコンプリートを起動する場合は、API によって自動的に処理されます)。

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

セッション トークンの詳細

オートコンプリートの結果を制限する

オートコンプリートの結果を特定の地域に限定したり、1 つ以上の場所のタイプまたは 5 か国まで結果をフィルタリングしたりできます。これらの制約は、オートコンプリート アクティビティ、AutocompleteSupportFragment、プログラマティック Autocomplete API に適用できます。

結果を制限する手順は次のとおりです。

  • 定義済みのリージョン内の結果を優先するには、setLocationBias() を呼び出します(定義済みのリージョン外からの結果が返される場合もあります)。
  • 定義されているリージョン内の結果のみを表示するには、setLocationRestriction() を呼び出します(定義済みのリージョン内の結果のみが返されます)。
  • 特定の場所のタイプに適合する結果のみを返すには、setTypesFilter() を呼び出します(たとえば、TypeFilter.ADDRESS を指定すると、正確な住所を持つ結果のみが返されます)。
  • 最大 5 つの国の結果のみを返すには、setCountries() を呼び出します。国は、ISO 3166-1 Alpha-2 に準拠した 2 文字の国コードで指定してください。

特定の地域を優先するよう結果にバイアスを設定する

オートコンプリートの結果を特定の地域に限定するには、setLocationBias() を呼び出して RectangularBounds を渡します。次のコード例は、フラグメントのインスタンスで setLocationBias() を呼び出して、オーストラリアのシドニーリージョンにオートコンプリートの候補を優先する方法を示しています。

Java


    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

      

Kotlin


    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

結果を特定の地域に制限する

オートコンプリートの結果を特定の地域に制限するには、setLocationRestriction() を呼び出して、RectangularBounds を渡します。次のコード例は、フラグメントのインスタンスで setLocationRestriction() を呼び出して、オーストラリアのシドニーリージョンにオートコンプリートの候補をバイアスする方法を示しています。

Java


    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

      

Kotlin


    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

注: この制限は、ルート全体にのみ適用されます。範囲の境界と重なるルートに基づいて、矩形の境界の外にある合成結果が返されることがあります。

場所のタイプまたは種類のコレクションで結果をフィルタする

オートコンプリート リクエストの結果から特定の場所タイプのみを取得するように制限できます。場所のタイプ、または場所のタイプの表 1、2、3 に示されているタイプ コレクションを使用してフィルタを指定します。何も指定しないと、すべてのタイプが返されます。

オートコンプリートの結果をフィルタリングするには、setTypesFilter() を呼び出してフィルタを設定します。

タイプまたはタイプ コレクション フィルタを指定するには:

  • setTypesFilter() を呼び出して、プレイスタイプに示されている表 1 と表 2 の値を最大 5 つ指定します。型の値は、PlaceTypes の定数によって定義されます。

  • setTypesFilter() を呼び出して、プレイスタイプに示す表 3 のタイプ コレクションを指定します。コレクション値は、PlaceTypes の定数によって定義されます。

    リクエストでは、表 3 のタイプのうち、1 つのみが許可されます。表 3 の値を指定する場合、表 1 または表 2 の値は指定できません。変更すると、エラーが発生します。

次のサンプルコードは、AutocompleteSupportFragmentsetTypesFilter() を呼び出し、複数の型値を指定しています。

Java


    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

      

Kotlin


    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

      

次のコード例では、AutocompleteSupportFragmentsetTypesFilter() を呼び出し、タイプ コレクションを指定して正確な住所の結果のみを返すフィルタを設定しています。

Java


    autocompleteFragment.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()));

      

Kotlin


    autocompleteFragment.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))

      

次のコード例では、IntentBuildersetTypesFilter() を呼び出し、タイプ コレクションを指定して、正確な住所の結果のみを返すフィルタを設定しています。

Java


    Intent intent = new Autocomplete.IntentBuilder(
        AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()))
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

結果を国でフィルタする

オートコンプリートの結果を最大で 5 か国に制限するには、setCountries() を呼び出して、国コードを設定します。次に、フィルタをフラグメントまたはインテントに渡します。国は、ISO 3166-1 Alpha-2 に準拠した 2 文字の国コードで指定してください。

次のコード例では、AutocompleteSupportFragment に対して setCountries() を呼び出し、指定した国の結果のみを返すフィルタを設定しています。

Java


    autocompleteFragment.setCountries("AU", "NZ");

      

Kotlin


    autocompleteFragment.setCountries("AU", "NZ")

      

使用量上限

Places SDK for Android などの Places API の使用量が、1 日あたりのリクエスト数(QPD)に制限されることはなくなりました。ただし、次の使用量上限は引き続き適用されます。

  • レート制限は 100 リクエスト/秒(QPS)です。これは、同じプロジェクトの認証情報を使用するすべてのアプリケーションのクライアント側およびサーバー側のリクエストの合計として計算されます。

アプリに属性を表示する

  • プログラムでオートコンプリート サービスを使用する場合は、UI に「Powered by Google」アトリビューションを表示するか、Google ブランドの地図内に表示する必要があります。
  • アプリでオートコンプリート ウィジェットを使用している場合、追加のアクションは不要です(必要なアトリビューションがデフォルトで表示されます)。
  • ID で場所を取得した後に追加の場所情報を取得して表示するには、サードパーティの属性も表示する必要があります。

詳細については、アトリビューションのドキュメントをご覧ください。

Place Autocomplete の最適化

このセクションでは、Place Autocomplete サービスを最大限に活用するためのヒントを紹介します。

概要は次のとおりです。

  • 機能的なユーザー インターフェースを最も手早く作成するには、Maps JavaScript API Autocomplete ウィジェット、Places SDK for Android Autocomplete ウィジェット、または Places SDK for iOS Autocomplete UI コントロールを使用します。
  • Place Autocomplete のデータ フィールドの基本を理解します。
  • 位置情報のバイアスと位置情報の制限のフィールドは省略可能ですが、オートコンプリートのパフォーマンスに大きく影響する場合があります。
  • エラー処理を使用して、API がエラーを返した場合に、アプリでグレースフル デグラデーションが行われるようにします。
  • アプリでは、選択肢がない場合でもユーザーが操作を続行できるようにします。

費用の最適化に関するヒント

基本的な費用の最適化

Place Autocomplete サービスの費用を最適化するには、Place Details と Place Autocomplete ウィジェットのフィールド マスクを使用して、必要な場所のデータ フィールドのみを返すよう設定します。

高度な費用の最適化

リクエストあたりの料金設定を利用し、Place Details の代わりに選択された場所に関する Geocoding API の結果をリクエストするためには、Place Autocomplete のプログラマティック実装を行うことをおすすめします。次の両方に該当する場合は、リクエストあたりの料金設定と Geocoding API を組み合わせた方が、セッションあたり(セッション ベース)の料金設定よりも費用対効果が高くなります。

  • ユーザーが選択した場所の緯度 / 経度または住所のみが必要な場合。その場合は、Geocoding API の方が、Place Details の呼び出しよりも少ないコストでこの情報を提供できます。
  • ユーザーが予測結果を選択するまでのオートコンプリート候補リクエストの回数が、平均 4 回以下の場合。その場合は、リクエストあたりの料金設定の方がセッションあたりの料金設定よりも費用対効果が高くなります。
ニーズに合った Place Autocomplete 実装を選ぶ際は、次の質問に対する答えを考え、それに対応するタブを選択するとヒントが表示されます。

アプリケーションで、選択された予測結果の住所と緯度 / 経度以外の情報が必要ですか?

はい。その他の情報も必要です

セッション ベースの Place Autocomplete と Place Details を併用します。
アプリケーションで、場所の名前、お店やサービスのステータス、始業時間などの Place Details が必要になるため、Place Autocomplete 実装では、セッション トークン(プログラマティック実装か、JavaScriptAndroid、または iOS ウィジェットへの組み込み)を使用することをおすすめします。合計では、セッションあたり 0.017 ドルに加え、リクエストするデータ フィールドに応じた対象のプレイスデータ SKU の費用がかかります。1

ウィジェット実装
セッション管理が JavaScriptAndroid、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Place Autocomplete リクエストと Place Details リクエストの両方が含まれます。必要なプレイスデータ フィールドのみをリクエストするように、必ず fields パラメータを指定してください。

プログラマティック実装
Place Autocomplete リクエストでセッション トークンを使用します。選択された予測結果に関する Place Details をリクエストする際は、次のパラメータを含めます。

  1. Place Autocomplete レスポンスの場所 ID
  2. Place Autocomplete リクエストで使用されるセッション トークン
  3. 必要な場所のデータ フィールドを指定する fields パラメータ

いいえ。住所と場所のみが必要です

Place Autocomplete 使用時のパフォーマンスによっては、アプリケーションで Places Details を使用するよりも、Geocoding API を使用した方が費用対効果が高くなる場合があります。アプリケーションのオートコンプリートの効率は、ユーザーの入力内容や、アプリケーションが使用される場所、パフォーマンス最適化のベスト プラクティスが導入されているかどうかによって変わります。

次の質問に答えるためには、ユーザーがアプリケーション内で Place Autocomplete の予測を選択するまでに、平均でどのくらいの文字数を入力するのかを分析する必要があります。

ユーザーが Place Autocomplete の予測を選択するまでに実行されるリクエスト数は、平均で 4 回以下ですか?

セッション トークンを使用せずにプログラムによって Place Autocomplete を実装し、選択された場所の予測で Geocoding API を呼び出します。
Geocoding API は、リクエスト 1 件につき 0.005 ドルで住所と緯度 / 経度の座標が提供されます。Place Autocomplete - Per Request のリクエスト 4 件の料金は 0.01132 ドルになるため、4 件のリクエストと、選択された場所予測に関する Geocoding API の呼び出しを合わせた料金は、0.01632 ドルになります。これは、Per Session Autocomplete でのセッション 1 回あたりの料金 0.017 ドルよりも少ないコストです。1

パフォーマンスに関するベスト プラクティスを導入し、できるだけ少ない入力文字数でユーザーが求める情報を提供できるようすることをおすすめします。

×

セッション ベースの Place Autocomplete と Place Details を併用します。
ユーザーが Place Autocomplete の予測を選択するまでの平均リクエスト回数が、セッションあたりの料金を超えるため、Place Autocomplete 実装では、Place Autocomplete リクエストと、関連する Place Details リクエストの両方でセッション トークンを使用することをおすすめします(合計費用はセッションあたり 0.017 ドル)。1

ウィジェット実装
セッション管理が JavaScriptAndroid、または iOS ウィジェットに自動的に組み込まれます。これには、選択された予測結果での Place Autocomplete リクエストと Place Details リクエストの両方が含まれます。基本データ フィールドのみをリクエストするように、必ず fields パラメータを指定してください。

プログラマティック実装
Place Autocomplete リクエストでセッション トークンを使用します。選択された予測結果に関する Place Details をリクエストする際は、次のパラメータを含めます。

  1. Place Autocomplete レスポンスの場所 ID
  2. Place Autocomplete リクエストで使用されるセッション トークン
  3. 住所やジオメトリなどの基本データ フィールドを指定する fields パラメータ

Place Autocomplete リクエストを遅らせることを検討する
ユーザーが最初の 3~4 文字を入力するまで Place Autocomplete リクエストを遅らせて、アプリケーションでのリクエスト数を減らすこともできます。たとえば、ユーザーが 3 文字目を入力してから、1 文字ごとに Place Autocomplete リクエストを行うとします。あるユーザーが、7 文字目を入力してから予測を選択し、Geocoding API リクエストが 1 回実行されました。この場合の合計費用は、0.01632 ドル(4 x Autocomplete Per Request 1 回の料金 0.00283 ドル + ジオコーディング 1 回の料金 0.005 ドル)となります。1

リクエストを遅らせることで、プログラマティック リクエストの回数を平均 4 回以下に抑えられる場合は、高パフォーマンスで Place Autocomplete と Geocoding API を併用する実装に関するガイダンスをご覧ください。なお、リクエストを遅らせると、1 文字入力するたびに予測が表示されはずと考えているユーザーには、遅延と受けとられる場合もあります。

パフォーマンスに関するベスト プラクティスを導入し、できるだけ少ない入力文字数でユーザーが求める情報を提供できるようすることをおすすめします。


  1. ここで提示されている料金は米ドルです。料金について詳しくは、Google Maps Platform の課金のページをご覧ください。

パフォーマンスに関するベスト プラクティス

Place Autocomplete のパフォーマンスを最適化するためのガイドラインは次のとおりです。

  • Place Autocomplete 実装に、国別のポリシー、場所のバイアス、言語設定(プログラマティック実装の場合)を追加します。ウィジェットはユーザーのブラウザやモバイル デバイスから言語設定を選択するため、ウィジェットでは言語設定は不要です。
  • Place Autocomplete が地図に関連付けられている場合は、地図のビューポートを基準に場所にバイアスをかけることができます。
  • ユーザーがいずれかのオートコンプリート候補を選択しなかった場合は(通常は目的の住所が候補に挙がらなかったことが原因)、ユーザーの元の入力内容を再利用して、より関連性の高い結果を取得できます。
    • ユーザーが住所情報のみを入力することが予想される場合は、Geocoding API の呼び出しで、ユーザーの元の入力内容を再利用します。
    • ユーザーが特定の場所に関する検索語句(名前や住所)を入力することが予想される場合は、Find Place リクエストを使用します。特定の地域の結果のみが求められる場合は、場所のバイアスを使用します。
    Geocoding API へのフォールバックが最適となるその他のシナリオは次のとおりです。
    • ユーザーがオーストラリア、ニュージーランド、カナダ以外の国で、建物の棟の住所を入力する場合。たとえば、米国の住所の「123 Bowdoin St #456, Boston MA, USA」はオートコンプリートではサポートされません(オートコンプリートがサポートしているのは、オーストラリア、ニュージーランド、カナダにある建物の棟の住所のみです。この 3 か国では、「9/321 Pitt Street, Sydney, New South Wales, Australia」、「14/19 Langana Avenue, Browns Bay, Auckland, New Zealand」、「145-112 Renfrew Dr, Markham, Ontario, Canada」などの形式の住所がサポートされます)。
    • ユーザーがニューヨークの「23-30 29th St, Queens」や、ハワイのカウアイ島の「47-380 Kamehameha Hwy, Kaneohe」など、道路区間のプレフィックスを入力する場合。

トラブルシューティング

さまざまなエラーが発生する可能性がありますが、アプリで発生する可能性が高いエラーの大半は、構成エラー(API キーの間違いや API キーの構成に誤りがあるなど)または割り当てエラー(アプリが割り当てを超過した)が原因で発生します。割り当ての詳細については、使用制限をご覧ください。

オートコンプリート コントロールの使用中に発生したエラーは、onActivityResult() コールバックで返されます。Autocomplete.getStatus() を呼び出して、結果のステータス メッセージを取得します。