テキスト検索（新版）

テキスト検索（新版）は、「渋谷 ピザショップ」「表参道 靴店」「123 番地」といった文字列に対して、場所のセットについての情報を返します。テキスト文字列に一致する場所のリストと、設定されている位置情報バイアスをレスポンスとして返します。

このサービスは、自動システムであいまいな住所のクエリを行う場合に特に便利です。文字列の住所以外の要素がビジネスと住所に一致する場合があります。あいまいな住所のクエリには、不適切な形式の住所や、お店やサービスの名前などの住所以外の要素を含むリクエストがあります。最初の 2 つの例のようなリクエストでは、ロケーション（地域、ロケーション制限、ロケーション バイアスなど）が設定されていない場合、0 の結果が返される可能性があります。

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

「10 High Street, UK」または「123 Main Street, US」 英国では複数の「High Street」、米国では複数の「Main Street」を指します。ロケーション制限が設定されていない場合、クエリは望ましい結果を返しません。
「チェーンレストラン ニューヨーク」 ニューヨークにある複数の「ChainRestaurant」の場所。番地や通りの名前は必要ありません。
「10 High Street, Escher UK」または「123 Main Street, Pleasanton US」 イギリスのエッシャー市には「ハイ ストリート」が 1 本のみ。米国のカリフォルニア州プレザントン市には「メイン ストリート」が 1 本しかない。
「UniqueRestaurantName New York」 ニューヨークにあるこの名前の施設は 1 つのみであり、区別するのに番地は必要ありません。
「東京のピザレストラン」 このクエリには地域の制限が含まれており、「ピザレストラン」は明確に定義された場所タイプです。複数の結果が返されます。
「+1 514-670-8700」

このクエリには電話番号が含まれています。その電話番号に関連付けられている場所について、複数の結果が返されます。

Text Search リクエスト

Text Search リクエストの形式は、次のとおりです。

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.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.NAME のみを含むようにフィールド リストを設定します。つまり、一致する各場所を表すレスポンスの Place オブジェクトには、この 2 つのフィールドのみが含まれます。

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

    • テキストクエリ文字列を「スパイシー ベジタリアン フード」に設定します。

    • 検索結果の場所の最大数を 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.NAME);

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

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

必須パラメータ

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

  • フィールド リスト

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

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

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

    • 次のフィールドで Text Search（ID のみ）SKU がトリガーされます。

      Place.Field.ID、 Place.Field.NAME

    • 次のフィールドで Text Search（Basic）SKU がトリガーされます。

      Place.Field.ADDRESS_COMPONENTS、Place.Field.BUSINESS_STATUS、Place.Field.ADDRESS、Place.Field.ICON_BACKGROUND_COLOR、Place.Field.ICON_URL、Place.Field.LAT_LNG、Place.Field.PHOTO_METADATAS、Place.Field.PLUS_CODE、Place.Field.TYPES、Place.Field.UTC_OFFSET、Place.Field.VIEWPORT、Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • 次のフィールドで Text Search（Advanced）SKU がトリガーされます。

      Place.Field.CURRENT_OPENING_HOURS、Place.Field.SECONDARY_OPENING_HOURS、Place.Field.PHONE_NUMBER、Place.Field.PRICE_LEVEL、Place.Field.RATING、Place.Field.OPENING_HOURS、Place.Field.USER_RATINGS_TOTAL、Place.Field.WEBSITE_URI

    • 次のフィールドで Text Search（Preferred）SKU がトリガーされます。

      Place.Field.CURBSIDE_PICKUP、Place.Field.DELIVERY、Place.Field.DINE_IN、Place.Field.EDITORIAL_SUMMARY、Place.Field.RESERVABLE、Place.Field.REVIEWS、Place.Field.SERVES_BEER、Place.Field.SERVES_BREAKFAST、Place.Field.SERVES_BRUNCH、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 オブジェクトを使用して、リクエストのオプション パラメータを指定します。

  • 含まれるタイプ

    検索結果を、Table A で定義されている指定されたタイプに一致する場所に制限します。1 つのタイプのみ指定できます。次に例を示します。

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

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

  • 場所のバイアス

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

    ロケーション制限またはロケーション バイアスを指定できますが、両方は指定できません。ロケーション制限は、結果が含まれるリージョンを指定するものと考えてください。ロケーション バイアスは、結果がエリアの近くにあっても、エリア外でもよいリージョンを指定するものと考えることができます。

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

    • 円は、中心点と半径（メートル単位）で定義します。radius は 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 の場合、経度の範囲が逆になります（ビューポートは経度線と交差します）。
      • 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 プレイスのデータベースで営業時間が指定されていない場所が返されます。

    open now パラメータを設定するには、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 に設定すると、インクルード タイプで指定されたタイプに一致する場所のみが返されます。false（デフォルト）の場合、指定したタイプと一致しない場所がレスポンスに含まれることがあります。

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