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
- 1 ~
ランク付けの設定
レスポンスでの結果のランク付け方法を指定します。該当する場合、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
の場合、レスポンスには指定されたタイプと一致しない場所が含まれることがあります。