テキスト検索（新版）

プラットフォームを選択: Android iOS JavaScript ウェブサービス

欧州経済領域（EEA）のデベロッパー

テキスト検索（新版）は、「渋谷 ピザショップ」「表参道 靴店」「123 番地」といった文字列に対して、場所のセットについての情報を返します。テキスト文字列と、その時点で設定済みの地域バイアスをもとに、場所のリストを返すサービスです。

テキスト検索（新版）では、必須パラメータに加えて、オプション パラメータを使用してクエリを絞り込み、より良い結果を得ることができます。

テキスト検索（新版）は、Nearby Search（新版）と似ています。2 つの主な違いは、テキスト検索（新版）では任意の検索文字列を指定できるのに対し、Nearby Search（新版）では検索する特定のエリアを指定する必要がある点です。

テキスト検索リクエスト

テキスト検索リクエストの形式は次のとおりです。

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchByText(searchByTextRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

この例では、次のことを行います。

  • フィールド リストを Place.Field.ID と Place.Field.DISPLAY_NAME のみを含むように設定します。つまり、一致する各場所を表すレスポンス内の Place オブジェクトには、これらの 2 つのフィールドのみが含まれます。

  • SearchByTextRequest.Builder を使用して、検索を定義する SearchByTextRequest オブジェクトを作成します。

    • テキストクエリ文字列を「Spicy Vegetarian Food」に設定します。

    • 結果の場所の最大数を 10 に設定します。デフォルト値および最大値は 20 です。

    • 検索範囲を、緯度と経度の座標で定義された長方形に制限します。このエリア外の一致は返されません。

  • OnSuccessListener を追加し、SearchByTextResponse オブジェクトから一致する場所を取得します。

テキスト検索のレスポンス

SearchByTextResponse クラスは、検索リクエストからのレスポンスを表します。SearchByTextResponse オブジェクトには、次のものが含まれます。

  • 一致するすべての場所を表す Place オブジェクトのリスト。一致する場所ごとに 1 つの Place オブジェクトが返されます。

  • 各 Place オブジェクトには、リクエストで渡されたフィールド リストで定義されたフィールドのみが含まれます。

たとえば、リクエストでフィールド リストを次のように定義したとします。

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

このフィールド リストは、レスポンス内の各 Place オブジェクトに、一致する各場所のプレイス ID と名前のみが含まれることを意味します。その後、Place.getId() メソッドと Place.getName() メソッドを使用して、各 Place オブジェクトのこれらのフィールドにアクセスできます。

Place オブジェクトのデータにアクセスするその他の例については、Place オブジェクトのデータ フィールドにアクセスするをご覧ください。

ページネーション

テキスト検索の SearchByTextResponse クラスは、getPagination() メソッドを介してテキスト検索結果のページネーションにアクセスできるようにします。このメソッドは Pagination オブジェクトを返します。

Pagination オブジェクトの hasNextPage() メソッドを使用して、追加の結果ページが利用可能かどうかを判断します。このメソッドはブール値（true または false）を返します。

hasNextPage() が true を返す間、fetchNextPage() メソッドを呼び出して結果の次のページを取得します。

次の例は、次のページが利用可能かどうかを確認してから、ページを読み込む方法を示しています。

Kotlin

val searchByTextRequest =
      searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) {
        maxResultCount = 10
      }

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener {response: SearchByTextResponse ->
        val places = response.places

        val pagination = response.pagination

        if (pagination.hasNextPage()) {
            pagination.setPageSize(20)
            pagination.fetchNextPage()
                    .addOnSuccessListener { nextPageResponse ->
                          val nextPagePlaces = nextPageResponse.getPlaces()
                    }
                    .addOnFailureListener {// Handle error with given status code}
        }
}
.addOnFailureListener {
// TODO: Handle error with given status code.
exception -> {
          exception.printStackTrace();
        }
}

Java

SearchByTextRequest searchByTextRequest =
  SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build();

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)
  .addOnSuccessListener((response) -> {
    List<Place> places = response.getPlaces();
    Log.i(TAG, "Places result: " + places);

    Pagination pagination =
      response.getPagination();

    if (pagination.hasNextPage()) {
      pagination.setPageSize(20); // change the page size from 10 to 20
      pagination.fetchNextPage()
    	  .addOnSuccessListener((nextPageResponse) -> {
            List<Place> nextPagePlaces = nextPageResponse.getPlaces();
            Log.i(TAG, "Next page places result: " + nextPagePlaces);
        });
    }
  })
  .addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
    	// Handle error with given status code
    }
  });

必須パラメータ

SearchByTextRequest の必須パラメータは次のとおりです。

  • フィールド リスト

    返す場所データ フィールドを指定します。返すデータ フィールドを指定する Place.Field 値のリストを渡します。レスポンスで返されるフィールドのデフォルト リストはありません。

    フィールド リストは、不要なデータをリクエストしないようにするための優れた設計手法です。これにより、不要な処理時間と請求料金を回避できます。

    次のフィールドを 1 つ以上指定します。

    • 次のフィールドは、テキスト検索 Essentials ID Only SKU をトリガーします。

      Place.Field.DISPLAY_NAME*
          * Place.Field.NAME（バージョン 4.0 で非推奨）の代わりに使用します。
      Place.Field.ID
      Place.Field.RESOURCE_NAME*
          * places/PLACE_ID 形式の場所のリソース名が含まれます。
           DISPLAY_NAME を使用して、場所のテキスト名にアクセスします。

      フィールドとその関連 SKU の完全なリストについては、プレイス データ フィールド（新版）をご覧ください。

    • 次のフィールドは テキスト検索 Pro SKU をトリガーします。

      Place.Field.ACCESSIBILITY_OPTIONS*
          Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE（非推奨）の代わりに使用します。
      Place.Field.ADDRESS_COMPONENTS
      Place.Field.ADR_FORMAT_ADDRESS
      Place.Field.BUSINESS_STATUS
      Place.Field.FORMATTED_ADDRESS*
          Place.Field.ADDRESS（非推奨）の代わりに使用します。
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
          Place.Field.ICON_URL（非推奨）の代わりに使用します。
      Place.Field.LOCATION*
          Place.Field.LAT_LNG（非推奨）の代わりに使用します。
      Place.Field.PHOTO_METADATAS
      Place.Field.PLUS_CODE
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.SHORT_FORMATTED_ADDRESS
      Place.Field.SUB_DESTINATIONS
      Place.Field.TYPES
      Place.Field.UTC_OFFSET
      Place.Field.VIEWPORT

      フィールドとその関連 SKU の完全なリストについては、プレイス データ フィールド（新版）をご覧ください。

    • 次のフィールドは、テキスト検索 Enterprise SKU をトリガーします。

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * 非推奨の Place.Field.PHONE_NUMBER の代わりに使用します。
      Place.Field.NATIONAL_PHONE_NUMBER
      Place.Field.OPENING_HOURS
      Place.Field.PRICE_LEVEL
      Place.Field.RATING
      Place.Field.SECONDARY_OPENING_HOURS
      Place.Field.USER_RATING_COUNT*
          * 非推奨の Place.Field.USER_RATINGS_TOTAL の代わりに使用します。
      Place.Field.WEBSITE_URI

      フィールドとその関連 SKU の完全なリストについては、プレイス データ フィールド（新版）をご覧ください。

    • 次のフィールドは、テキスト検索 Enterprise Plus SKU をトリガーします。

      Place.Field.ALLOWS_DOGS
      Place.Field.CURBSIDE_PICKUP
      Place.Field.DELIVERY
      Place.Field.DINE_IN
      Place.Field.EDITORIAL_SUMMARY
      Place.Field.EV_CHARGE_OPTIONS
      Place.Field.FUEL_OPTIONS
      Place.Field.GOOD_FOR_CHILDREN
      Place.Field.GOOD_FOR_GROUPS
      Place.Field.GOOD_FOR_WATCHING_SPORTS
      Place.Field.LIVE_MUSIC
      Place.Field.MENU_FOR_CHILDREN
      Place.Field.OUTDOOR_SEATING
      Place.Field.PARKING_OPTIONS
      Place.Field.PAYMENT_OPTIONS
      Place.Field.RESERVABLE
      Place.Field.RESTROOM
      Place.Field.REVIEWS
      Place.Field.SERVES_BEER
      Place.Field.SERVES_BREAKFAST
      Place.Field.SERVES_BRUNCH
      Place.Field.SERVES_COCKTAILS
      Place.Field.SERVES_COFFEE
      Place.Field.SERVES_DESSERT
      Place.Field.SERVES_DINNER
      Place.Field.SERVES_LUNCH
      Place.Field.SERVES_VEGETARIAN_FOOD
      Place.Field.SERVES_WINE
      Place.Field.TAKEOUT

      フィールドとその関連 SKU の完全なリストについては、プレイス データ フィールド（新版）をご覧ください。

    フィールド リスト パラメータを設定するには、SearchByTextRequest オブジェクトの作成時に setPlaceFields() メソッドを呼び出します。

  • テキストクエリ

    検索するテキスト文字列（「レストラン」、「123 番通り」、「サンフランシスコのおすすめスポット」など）。API はこの文字列と一致する候補を、関連性の高い順に並べて結果として返します。

    テキスト クエリ パラメータを設定するには、SearchByTextRequest オブジェクトをビルドするときに setTextQuery() メソッドを呼び出します。

オプション パラメータ

SearchByTextRequest オブジェクトを使用して、リクエストのオプション パラメータを指定します。

  • 含まれるタイプ

    表 A で定義された、指定したタイプに一致する場所のみに結果を制限します。指定できるタイプは 1 つだけです。次に例を示します。

    • setIncludedType("bar")
    • setIncludedType("pharmacy")

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

  • 位置情報のバイアス

    検索する領域を指定します。この位置はバイアスとして機能します。つまり、指定された位置周辺の結果が返される可能性があります。指定されたエリア外の結果も含まれます。

    位置情報の制限または位置情報のバイアスのいずれかを指定できますが、両方を指定することはできません。位置情報の制限は、結果がその範囲内になければならない地域を指定するもので、位置情報のバイアスは、結果がその範囲内またはその近くにある可能性が高い地域を指定するものです。位置情報のバイアスを使用する場合、結果が指定されたエリア外になる可能性があることに注意してください。

    地域を長方形のビューポートまたは円として指定します。

    • 円は、中心点と半径（メートル単位）で定義されます。半径は 0.0 ～ 50000.0 の範囲で指定する必要があります。次に例を示します。

      // Define latitude and longitude coordinates of the center of the search area.
LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);

// Use the builder to create a SearchByTextRequest object.
// Set the radius of the search area to 500.0 meters.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();

    • 長方形は、対角線上の 2 つの低点と高点として表される緯度経度のビューポートです。低点は長方形の南西隅を示し、高点は長方形の北東隅を示します。

      ビューポートは閉じた領域と見なされます。つまり、境界が含まれます。緯度の範囲は -90 ～ 90 度、経度の範囲は -180 ～ 180 度にする必要があります。

      • low = high の場合、ビューポートはその単一点で構成されます。
      • low.longitude > high.longitude の場合、経度範囲は反転します（ビューポートが経度 180 度の線を横切ります）。
      • low.longitude = -180 度、high.longitude = 180 度の場合は、ビューポートにすべての経度が含まれます。
      • low.longitude = 180 度、high.longitude = -180 度の場合、経度範囲は空になります。
      • low.latitude > high.latitude の場合、緯度の範囲は空です。

      下限と上限の両方に値を入力する必要があります。また、表されるボックスを空にすることはできません。ビューポートが空の場合、エラーが発生します。

      たとえば、長方形のビューポートについては、テキスト検索リクエストをご覧ください。

      位置情報のバイアス パラメータを設定するには、SearchByTextRequest オブジェクトをビルドするときに setLocationBias() メソッドを呼び出します。

  • ロケーションの制限

    検索するエリアを指定します。指定したエリア外の結果は返されません。地域を長方形の Viewport として指定します。ビューポートの定義については、位置情報のバイアスの説明をご覧ください。

    位置情報の制限または位置情報のバイアスのいずれかを指定できますが、両方を指定することはできません。位置情報の制限は、結果がその範囲内になければならない地域を指定するもので、位置情報のバイアスは、結果がその範囲の近くになければならないが、範囲外でもよい地域を指定するものと考えてください。

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

  • 最大結果数

    返される場所の結果の最大数を指定します。1 ～ 20（デフォルト）の範囲で指定する必要があります。

    最大結果数パラメータを設定するには、SearchByTextRequest オブジェクトの作成時に setMaxResultCount() メソッドを呼び出します。

  • 評価の下限

    結果を、ユーザーの平均評価がこの上限以上のものに制限します。値は 0.0 ～ 5.0（指定した値を含む）の範囲で 0.5 刻みで指定する必要があります。たとえば、0、0.5、1.0、...、5.0（5.0 を含む）などです。値は最も近い 0.5 に切り上げられます。たとえば、値を 0.6 にすると、評価が 1.0 未満の結果がすべて除外されます。

    最小レーティング パラメータを設定するには、SearchByTextRequest オブジェクトを作成するときに setMinRating() メソッドを呼び出します。

  • 募集中

    true の場合、クエリが送信された時点で営業している場所のみが返されます。false の場合、営業ステータスに関係なくすべてのビジネスを返します。このパラメータを false に設定すると、Google プレイスのデータベースに営業時間が登録されていない場所も返されます。

    今すぐ営業中パラメータを設定するには、SearchByTextRequest オブジェクトを作成するときに setOpenNow() メソッドを呼び出します。

  • 価格帯

    デフォルトでは、すべての価格帯のサービスを提供する場所が結果に含まれます。結果を特定の料金レベルの場所のみに制限するには、返したい場所の料金レベルに対応する整数値のリストを渡します。

    • 1 - 安価なサービスを提供している。
    • 2 - 手頃な価格のサービスを提供している。
    • 3 - 高価なサービスを提供している場所。
    • 4 - 非常に高額なサービスを提供している場所。

    価格レベルのパラメータを設定するには、SearchByTextRequest オブジェクトの作成時に setPriceLevels() メソッドを呼び出します。

  • ランクの優先度

    クエリのタイプに基づいて、レスポンスで結果をランク付けする方法を指定します。

    • 「ニューヨークのレストラン」などのカテゴリ検索の場合、SearchByTextRequest.RankPreference.RELEVANCE（検索の関連性で結果をランク付け）がデフォルトです。ランク設定は SearchByTextRequest.RankPreference.RELEVANCE または SearchByTextRequest.RankPreference.DISTANCE（距離で結果をランク付け）に設定できます。
    • 「Mountain View, CA」などのカテゴリ以外のクエリの場合は、ランク設定パラメータを未設定のままにすることをおすすめします。

    ランクの優先度パラメータを設定するには、SearchByTextRequest オブジェクトをビルドするときに setRankPreference() メソッドを呼び出します。

  • 地域コード

    レスポンスの形式設定に使用されるリージョン コード。 2 文字の CLDR コード値として指定します。このパラメータは、検索結果にバイアス効果を与えることもあります。デフォルト値はありません。

    レスポンスのアドレス フィールドの国名がリージョン コードと一致する場合、国コードはアドレスから省略されます。

    大半の CLDR コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」（.co.uk）ですが、ISO 3166-1 コードは「gb」（厳密には「グレート ブリテンおよび北アイルランド連合王国」のエンティティ）です。このパラメータは、適用される法律に基づいて結果に影響を与える可能性があります。

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

  • 厳格な型フィルタリング

    include 型パラメータとともに使用されます。true に設定すると、include type で指定されたタイプに一致する場所のみが返されます。false（デフォルト）の場合、レスポンスには指定されたタイプと一致しない場所が含まれることがあります。

    厳格なタイプ フィルタリング パラメータを設定するには、SearchByTextRequest オブジェクトの作成時に setStrictTypeFiltering() メソッドを呼び出します。