テキスト検索（新版）

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

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

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

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

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

Text Search リクエスト

Text 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 オブジェクトから一致する場所を取得します。

Text Search レスポンス

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 オブジェクトのデータ フィールドにアクセスするをご覧ください。

必須パラメータ

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

  • フィールド リスト

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

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

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

    • 次のフィールドは、Text Search 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 を使用して、場所のテキスト名にアクセスします。

    • 次のフィールドは、Text Search 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

    • 次のフィールドは Text Search 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

    • 次のフィールドは Text Search 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

    フィールド リスト パラメータを設定するには、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() メソッドを呼び出します。

  • 地域の制限

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

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

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

  • 結果の最大数

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

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

  • 評価の下限

    結果を、ユーザーの平均評価がこの上限以上のものに制限します。値は 0.0 ～ 5.0（指定した値を含む）の範囲で 0.5 刻みで指定する必要があります。たとえば、0、0.5、1.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 タイプで指定された指定タイプに一致する場所のみが返されます。デフォルトの false の場合、レスポンスには指定されたタイプと一致しない場所が含まれることがあります。

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