テキスト検索

Text Search では、文字列に基づいて場所のセットに関する情報が返されます。たとえば、「渋谷 ピザショップ」や「新宿近くの靴店」、「中央通り 123 番地」などが返されます。このサービスは、テキスト文字列と、設定された場所のバイアスに一致する場所のリストをレスポンスとして返します。

このサービスは、自動システムであいまいな住所のクエリを行う場合に特に有用です。文字列の住所以外の構成要素は、住所だけでなく企業や店舗とも一致します。あいまいな住所クエリの例としては、形式が不適切な住所や、ビジネス名などの住所以外の要素を含むリクエストなどがあります。最初の 2 つの例のようなリクエストでは、ロケーション（リージョン、ロケーション制限、ロケーション バイアスなど）が設定されていなければ、結果はゼロになる可能性があります。

「10 High Street, UK」または「123 Main Street, US」 英国には複数の「High Street」、米国には複数の「Main Street」があります。ロケーション制限が設定されていない場合、クエリから望ましい結果が返されません。
「チェーン レストラン ニューヨーク」 ニューヨークに複数の「ChainRestaurant」の場所がある。番地や通りの名前はない。
「10 High Street, Escher UK」または「123 Main Street, Pleasanton US」 英国のエッシャー市に「High Street」が 1 つだけ、米国カリフォルニア州プレザントンで「Main Street」が 1 つだけある。
「Unique レストラン Name 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 オブジェクト内のデータにアクセスする例については、プレイス オブジェクトのデータ フィールドにアクセスするをご覧ください。

必須パラメータ

  • フィールド リスト

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

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

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

    • 次のフィールドによって Text Search (ID Only) 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

  • テキストクエリ

    検索するテキスト文字列（例: 「レストラン」、「メイン ストリート 123」、「サンフランシスコのおすすめ場所」）。API はこの文字列と一致する候補を返し、関連性の高い順に結果を並べ替えます。

省略可能なパラメータ

これらのパラメータは、SearchByTextRequest.Builder のメソッドを使用して設定します。たとえば、結果の最大数を設定するには、SearchByTextRequest.Builder.setMaxResultCount() を呼び出します。

  • 含まれるタイプ

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

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

  • 場所のバイアス

    検索する領域を指定します。この場所はバイアスとして機能します。つまり、指定された場所の周辺にある結果（指定された領域外の結果を含む）を返すことができます。

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

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

    • 円は、中心点と半径（メートル単位）で定義されます。radius は 0.0 ～ 50000.0 の範囲で指定する必要があります。デフォルトの radius は 0.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 の場合、緯度の範囲は空になります。

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

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

  • 地域の制限

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

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

  • 最大結果数

    返されるプレイスの結果の最大数を指定します。1 ～ 20（デフォルト）の値にする必要があります。

  • 評価の下限

    結果は、平均ユーザー評価がこの上限以上のもののみに限定されます。値は 0.0 ～ 5.0 の範囲で指定し、0.5 単位で指定します。例: 0、0.5、1.0、...、5.0（両端を含む）。値は 0.5 単位で切り上げられます。たとえば、値を 0.6 にすると、評価 1.0 未満の結果がすべて除外されます。

  • 営業中

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

  • 価格帯

    検索対象を特定の価格レベルでマークされている場所に限定します。デフォルトでは、すべての価格レベルが選択されます。

    次の整数値を 1 つ以上含むリストを指定します。

    • 1 ～PRICE_LEVEL_INEXPENSIVE
    • 2 ～PRICE_LEVEL_MODERATE
    • 3 ～PRICE_LEVEL_EXPENSIVE
    • 4 ～PRICE_LEVEL_VERY_EXPENSIVE

  • ランク付けの設定

    レスポンスでの結果のランク付け方法を指定します。該当する場合、API はデフォルトで RELEVANCE を使用します。たとえば、「ニューヨーク市のレストラン」というクエリの場合、RELEVANCE がデフォルトです。「Mountain View, CA」などの地理的クエリやその他のタイプのクエリの場合、デフォルトは適用されず、結果はバックエンドから返される順序で表示されます。

    次の値があります。

    • SearchByTextRequest.RankPreference.DISTANCE: 距離で結果をランク付けします。
    • SearchByTextRequest.RankPreference.RELEVANCE: 関連性によって結果をランク付けします。

  • 地域コード

    レスポンスのフォーマットに使用するリージョン コード。 2 文字の CLDR コード値で指定します。このパラメータは、検索結果にバイアス効果を及ぼすこともできます。デフォルト値はありません。

    レスポンスの住所フィールドの国名が地域コードと一致する場合、国コードは住所から除外されます。

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

  • 厳密なタイプのフィルタリング

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