テキスト検索（新版）

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

Text Search（新版）は、「渋谷 ピザショップ」「表参道 靴店」「123 番地」といった文字列に対して、場所のセットについての情報を返します。このサービスは、テキスト文字列や場所の優先度設定と合致するプレイスのリストをレスポンスとして返します。

このサービスは、自動システムであいまいな住所をクエリする場合に特に便利です。文字列の住所以外の構成要素を、店舗や住所と照合できます。あいまいな住所のクエリには、不適切な形式の住所、店舗名など住所以外の要素を含むリクエストなどがあります。最初の 2 つの例のようなリクエストでは、地域、地域の制限、位置情報の偏向などの位置情報が設定されていない限り、結果が 0 件になることがあります。

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

「10 High Street, UK」または「123 Main Street, US」	英国では複数の「High Street」、米国では複数の「Main Street」が存在する。 位置情報の制限が設定されていない限り、クエリで望ましい結果が返されません。
「ChainRestaurant New York」	ニューヨークに複数の「ChainRestaurant」の店舗があり、住所や通りの名前が指定されていない。
「10 High Street, Escher UK」または「123 Main Street, Pleasanton US」	英国の Escher 市には「High Street」が 1 つしかなく、米国の Pleasanton CA 市には「Main Street」が 1 つしかありません。
「UniqueRestaurantName New York」	ニューヨークにこの名前の施設は 1 か所のみです。区別するために住所は必要ありません。
「ニューヨークのピザレストラン」	このクエリには場所の制限が含まれており、「ピザレストラン」は明確に定義された場所のタイプです。複数の結果が返されます。
「[phone]」	このクエリには電話番号が含まれています。その電話番号に関連付けられている場所の複数の結果が返されます。 注: 電話番号で検索する場合は、国コードの後にスペースを挿入し、国コードに対応する region code パラメータを設定すると、より良い結果が得られます。

注: テキスト検索（新規）は、Places SDK for Android バージョン 3.3.0 以降で利用できます。詳細については、SDK バージョンを選択するをご覧ください。バージョン 4.0.0 で追加された Kotlin API の使用方法については、リファレンスの概要をご覧ください。

Text Search リクエスト

注: テキスト検索は Places SDK for Android（新規）の一部であり、Places SDK for Android では使用できません。

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

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

注: PlacesClient の初期化について詳しくは、Places API クライアントを初期化するをご覧ください。

CancellationToken を使用して、任意のリクエストクラス（FetchPlaceRequest など）へのリクエストのキャンセルを試行できます。キャンセルはベスト エフォート ベースで実行されます。キャンセル リクエストが送信されると、レスポンスは返されません。キャンセル トークンを発行しても、特定のリクエストがキャンセルされるとは限りません。また、レスポンスが返されなくても、リクエストに対して料金が請求される場合があります。

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 (ID Only) SKU をトリガーします。

    Place.Field.DISPLAY_NAME、Place.Field.ID、Place.Field.RESOURCE_NAME、
    
    注:

    • Place.Field.NAME フィールドは、Places SDK for Android バージョン 4.0 で非推奨になりました。代わりに Place.Field.DISPLAY_NAME を使用してください。
    • RESOURCE_NAME フィールドには、places/PLACE_ID 形式の場所リソース名が格納されます。DISPLAY_NAME を使用して、場所のテキスト名にアクセスします。

  • 次のフィールドは Text Search (Basic) SKU をトリガーします。

    Place.Field.ACCESSIBILITY_OPTIONS、Place.Field.ADDRESS_COMPONENTS、Place.Field.ADR_FORMAT_ADDRESS、Place.Field.BUSINESS_STATUS、Place.Field.FORMATTED_ADDRESS、Place.Field.GOOGLE_MAPS_URI、Place.Field.ICON_BACKGROUND_COLOR、Place.Field.ICON_MASK_URL、Place.Field.LOCATION、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、
    
    注: Place.Field.ADDRESS、Place.Field.ICON_URL、Place.Field.LAT_LNG、Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE フィールドは、Places SDK for Android バージョン 4.0 で非推奨になりました。代わりに、Place.Field.FORMATTED_ADDRESS、Place.Field.ICON_MASK_URL、Place.Field.LOCATION、Place.ACCESSIBILITY_OPTIONS を使用します。Place.Field.ACCESSIBILITY_OPTIONS は Place Details（新規）でのみ使用できます。

  • 次のフィールドは、Text Search (Advanced) SKU をトリガーします。

    Place.Field.CURRENT_OPENING_HOURS、Place.Field.CURRENT_SECONDARY_OPENING_HOURS、Place.Field.INTERNATIONAL_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.WEBSITE_URI、
    
    注: Place.Field.PHONE_NUMBER フィールドと Place.Field.USER_RATINGS_TOTAL フィールドは、Places SDK for Android バージョン 4.0 で非推奨になりました。代わりに、それぞれ Place.Field.INTERNATIONAL_PHONE_NUMBER と Place.USER_RATING_COUNT を使用してください。

  • 次のフィールドは、Text Search (Preferred) 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
  注: Places SDK for Android バージョン 4.0 では、いくつかの Place データフィールドが非推奨になり、新しいフィールドが追加されました。詳しくは、Places SDK for Android 4.0 の新しい場所データフィールドに移行する をご覧ください。

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

• テキストクエリ

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

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

オプション パラメータ

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

• 含まれるタイプ

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

  • setIncludedType("bar")
  • setIncludedType("pharmacy")
  注: 表 B の値はレスポンスでのみ返されます。表 B の値をフィルタとして使用することはできません。

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

• 位置情報バイアス

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

  地域の制限または地域の偏向のいずれかを指定できますが、両方を指定することはできません。位置情報の制限は、結果が含まれる必要がある地域を指定するもので、位置情報バイアスは、結果が含まれる可能性が高い地域を指定するものです。位置情報バイアスを使用する場合でも、結果が指定されたエリアの外部に存在する可能性があることに注意してください。

  注: 位置情報バイアスと位置情報制限の両方を省略すると、API はデフォルトで IP バイアスを使用します。IP バイアスを使用すると、API はデバイスの IP アドレスを使用して結果をバイアスします。
  注: textQuery に Market in Barcelona などの明示的なロケーションが含まれている場合は、locationBias パラメータをオーバーライドできます。この場合、locationBias は無視されます。

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

  • 円は、中心点と半径（メートル単位）で定義されます。半径は 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() メソッドを呼び出します。

• 地域の制限

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

  地域の制限または地域の偏向のいずれかを指定できますが、両方を指定することはできません。ロケーション制限は、結果が含まれる必要があるリージョンを指定する方法です。ロケーション バイアスは、結果が近い必要があるリージョンを指定する方法です。ただし、そのリージョンの外側に結果があってもかまいません。

  注: 位置情報バイアスと位置情報制限の両方を省略すると、API はデフォルトで IP バイアスを使用します。IP バイアスを使用すると、API はデバイスの IP アドレスを使用して結果をバイアスします。

  位置情報の制限パラメータを設定するには、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 - 非常に高額なサービスを提供している場所。
  注: 場所が無料サービスを提供していることを示す整数値 0 はレスポンスに含めることができますが、リクエストのフィルタ値として使用することはできません。

  価格レベル パラメータを設定するには、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」（厳密には「United Kingdom of Great Britain and Northern Ireland」のエンティティ）です。このパラメータは、適用される法律に基づいて結果に影響する可能性があります。

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

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

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

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