Text Search は、文字列に基づいて一連の場所に関する情報を返します。例: 「渋谷 ピザ屋」、「新宿 2 丁目付近の靴店」、「中央通り 123」。テキスト文字列と、設定された場所のバイアスに一致するプレイスのリストをレスポンスとして返します。
このサービスは、自動システムであいまいな住所クエリを行う場合に特に有用です。文字列の住所以外の構成要素は、住所だけでなく企業や店舗とも一致します。あいまいな住所クエリの例としては、形式が不適切な住所や、ビジネス名などの住所以外の構成要素を含むリクエストなどがあります。最初の 2 つの例のようなリクエストでは、ロケーション(リージョン、ロケーション制限、ロケーション バイアスなど)が設定されていなければ、結果が 0 を返すことがあります。
「10 High Street, UK」または「123 Main Street, US」 | 英国には複数の「High Street」、米国には複数の「Main Street」があります。ロケーション制限が設定されていない場合、クエリから望ましい結果が返されません。 |
「ニューヨークのレストラン チェーン」 | ニューヨークに「チェーン レストラン」が複数あり、番地や通りの名前がない。 |
「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」 | このクエリには電話番号が含まれています。その電話番号に関連付けられている場所について、複数の結果が返されます。 |
テキスト検索で場所のリストを取得する
GMSPlacesClient
searchByTextWithRequest:
を呼び出して Text Search リクエストを作成し、リクエスト パラメータを定義する GMSPlaceSearchByTextRequest
オブジェクトと、レスポンスを処理する GMSPlaceSearchByTextResultCallback
タイプのコールバック メソッドを渡します。
GMSPlaceSearchByTextRequest
オブジェクトでは、リクエストのすべての必須パラメータと任意のパラメータを指定します。必須パラメータは次のとおりです。
GMSPlace
オブジェクトで返すフィールドのリスト。フィールド マスクとも呼ばれます。GMSPlaceProperty
で定義します。フィールド リストでフィールドを 1 つも指定していない場合、またはフィールド リストを省略すると、呼び出しでエラーが返されます。- テキストクエリ。
このテキスト検索リクエストの例では、レスポンスの GMSPlace
オブジェクトに、検索結果の各 GMSPlace
オブジェクトの場所名とプレイス ID が含まれていることを指定しています。また、レスポンスをフィルタして、「レストラン」タイプの場所のみを返します。
Swift
// Create the GMSPlaceSearchByTextRequest object. let placeProperties: [GMSPlaceProperty] = [GMSPlacePropertyName, GMSPlacePropertyPlaceID]; let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York" placeProperties:placeProperties) request.isOpenNow = true request.includedType = "restaurant" request.maxResultCount = 5 request.minRating = 3.5 request.rankPreference = .distance request.isStrictTypeFiltering = true request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue] request.locationRestriction = GMSPlaceRectangularLocationOption( CLLocationCoordinate2D(latitude: 20, longitude: 30), CLLocationCoordinate2D(latitude: 40, longitude: 50) ) // Array to hold the places in the response placeResults = []; let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in guard let self, error == nil else { if let error { print(error.localizedDescription) } return } guard let results = results as? [GMSPlace] else { return } self.placeResults = results } GMSPlacesClient.shared().searchByTextWithRequest(with: request, callback: callback)
Objective-C
// Create the GMSPlaceSearchByTextRequest object. GMSPlaceSearchByTextRequest *request = [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]]; request.isOpenNow = YES; request.includedType = @"restaurant"; request.maxResultCount = 5; request.minRating = 3.5; request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance; request.isStrictTypeFiltering = YES; request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ]; request.locationRestriction = GMSPlaceRectangularLocationOption( CLLocationCoordinate2DMake(20, 30), CLLocationCoordinate2DMake(40, 50)); request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(20, 30), 2.0); // Array to hold the places in the response _placeResults = [NSArray array]; // Create the GMSPlaceSearchByTextRequest object. [_placesClient searchByTextWithRequest:request callback:^(NSArray<GMSPlace *> _Nullable placeResults, NSError * _Nullable error) { if (placeResults.count > 0) { // Get list of places. _placeResults = placeResults; } }];
GooglePlacesSwift
let restriction = RectangularLocationRestriction( northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30), southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50) ) let searchByTextRequest = SearchByTextRequest( textQuery: "pizza in New York", placeProperties: [ .name, .placeID ], locationRestriction: restriction, includedType: .restaurant, maxResultCount: 5, minRating: 3.5, priceLevels: [ .moderate, .inexpensive ], isStrictTypeFiltering: true ) switch await placesClient.searchByText(with: searchByTextRequest) { case .success(let places): // Handle places case .failure(let placesError): // Handle error }
Text Search のレスポンス
Text Search API は、一致する場所ごとに 1 つの GMSPlace
オブジェクトを含む GMSPlace
オブジェクトの形式で一致の配列を返します。
レスポンスの GMSPlace
オブジェクトには、データ フィールドに加えて、次のメンバー関数が含まれています。
-
isOpen
は、指定された時間に場所が営業しているかどうかを計算します。 isOpenAtDate
は、特定の日に場所が営業しているかどうかを計算します。
必須パラメータ
GMSPlaceSearchByTextRequest
オブジェクトを使用して、検索に必要なパラメータを指定します。
-
フィールド リスト
返す場所データ プロパティを指定します。返されるデータ フィールドを指定する
GMSPlace
プロパティのリストを渡します。フィールド マスクを省略すると、リクエストはエラーを返します。フィールド リストは、不要なデータをリクエストしないようにするための優れた設計上の方法です。これにより、不要な処理時間と課金を回避できます。
以下のフィールドを 1 つ以上指定します。
次のフィールドによって Text Search (ID Only) SKU がトリガーされます。
GMSPlacePropertyPlaceID
、GMSPlacePropertyName
次のフィールドによって Text Search(Basic)SKU がトリガーされます。
GMSPlacePropertyAddressComponents
、GMSPlacePropertyBusinessStatus
、GMSPlacePropertyFormattedAddress
、GMSPlacePropertyIconBackgroundColor
、GMSPlacePropertyIconImageURL
、GMSPlacePropertyCoordinate
、GMSPlacePropertyPhotos
、GMSPlacePropertyPlusCode
、GMSPlacePropertyTypes
、GMSPlacePropertyUTCOffsetMinutes
、GMSPlacePropertyViewport
、GMSPlacePropertyWheelchairAccessibleEntrance
次のフィールドによって Text Search (Advanced) SKU がトリガーされます。
GMSPlacePropertyCurrentOpeningHours
、GMSPlacePropertySecondaryOpeningHours
、GMSPlacePropertyPhoneNumber
、GMSPlacePropertyPriceLevel
、GMSPlacePropertyRating
、GMSPlacePropertyOpeningHours
、GMSPlacePropertyUserRatingsTotal
、GMSPlacePropertyWebsite
次のフィールドによって Text Search(Preferred)SKU がトリガーされます。
GMSPlacePropertyCurbsidePickup
、GMSPlacePropertyDelivery
、GMSPlacePropertyDineIn
、GMSPlacePropertyEditorialSummary
、GMSPlacePropertyReservable
、GMSPlacePropertyReviews
、GMSPlacePropertyServesBeer
、GMSPlacePropertyServesBreakfast
、GMSPlacePropertyServesBrunch
、GMSPlacePropertyServesDinner
、GMSPlacePropertyServesLunch
、GMSPlacePropertyServesVegetarianFood
、GMSPlacePropertyServesWine
、GMSPlacePropertyTakeout
-
textQuery
検索するテキスト文字列(「レストラン」、「123 メイン ストリート」、「サンフランシスコのおすすめ場所」など)。
省略可能なパラメータ
GMSPlaceSearchByTextRequest
オブジェクトを使用して、検索のオプション パラメータを指定します。
includedType
結果を、表 A で定義された指定タイプに一致する場所に制限します。指定できるタイプは 1 つのみです。次に例を示します。
request.includedType = "bar"
request.includedType = "pharmacy"
isOpenNow
true
の場合、クエリが送信された時点で営業している場所のみを返します。false
の場合、営業ステータスに関係なく、すべてのビジネスを返します。このパラメータをfalse
に設定すると、Google プレイスのデータベースに営業時間が登録されていない場所が返されます。isStrictTypeFiltering
includeType
パラメータとともに使用します。true
に設定すると、includeType
で指定されたタイプに一致する場所のみが返されます。false の場合、デフォルトでは、指定したタイプと一致しない場所がレスポンスに含まれる可能性があります。locationBias
検索する領域を指定します。この場所はバイアスとして機能します。つまり、指定された場所の周辺にある結果(指定された領域外の結果を含む)を返すことができます。
locationRestriction
またはlocationBias
を指定できます。両方は指定できません。locationRestriction
は結果が存在するリージョンを指定するものと考えてください。locationBias
は結果が存在するものの近くのリージョンを指定するもので、領域の外にあってもよいと考えてください。領域を長方形のビューポートまたは円として指定します。
円は、中心点と半径(メートル単位)で定義されます。radius は 0.0 ~ 50000.0 の範囲で指定する必要があります。デフォルトの radius は 0.0 です。次に例を示します。
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(latitude: 20, longitude: 30), radius: 2.0)
長方形は緯度と経度のビューポートで、対角線上に並ぶ 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
の場合、緯度の範囲は空になります。
locationRestriction
検索する領域を指定します。指定された領域外の結果は返されません。領域を長方形のビューポートとして指定します。ビューポートの定義については、
locationBias
の説明をご覧ください。locationRestriction
またはlocationBias
を指定できます。両方は指定できません。locationRestriction
は結果が存在するリージョンを指定するものと考えてください。locationBias
は結果が存在するものの近くのリージョンを指定するもので、領域の外にあってもよいと考えてください。-
maxResultCount
返されるプレイスの結果の最大数を指定します。1 ~ 20(デフォルト)の値にする必要があります。
minRating
結果は、平均ユーザー評価がこの上限以上のもののみに限定されます。値は 0.0 ~ 5.0 の範囲で指定し、0.5 単位で指定します。例: 0、0.5、1.0、...、5.0(両端を含む)。値は 0.5 単位で切り上げられます。たとえば、値を 0.6 にすると、評価 1.0 未満の結果がすべて除外されます。
-
priceLevels
検索対象を特定の価格レベルでマークされている場所に限定します。デフォルトでは、すべての価格レベルが選択されます。
PriceLevel
で定義された 1 つ以上の値の配列を指定します。次に例を示します。
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
rankPreference
クエリのタイプに基づいて、レスポンスでの結果のランク付け方法を指定します。
- 「東京のレストラン」のようなカテゴリクエリの場合、デフォルトは
.relevance
(検索結果の関連性によるランク付け)です。rankPreference
は.relevance
または.distance
に設定できます(距離によって結果をランク付けします)。 - 「Mountain View, CA」などのカテゴリ以外のクエリの場合は、
rankPreference
を未設定のままにすることをおすすめします。
- 「東京のレストラン」のようなカテゴリクエリの場合、デフォルトは
regionCode
レスポンスのフォーマットに使用するリージョン コード。 2 文字の CLDR コード値で指定します。このパラメータは、検索結果にバイアス効果を及ぼすこともできます。デフォルト値はありません。
レスポンスの住所フィールドの国名が地域コードと一致する場合、国コードは住所から除外されます。
ほとんどの CLDR コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」(.co.uk)ですが、ISO 3166-1 コードは「gb」(厳密には「グレート ブリテンおよび北アイルランド連合王国」の法人を意味します)です。パラメータは、適用される法律に基づいて結果に影響を与える可能性があります。
アプリに属性を表示する
アプリが GMSPlacesClient
から取得した情報(写真やレビューなど)を表示する場合、必要な属性も表示する必要があります。
たとえば、GMSPlacesClient
オブジェクトの reviews
プロパティには、最大 5 つの GMSPlaceReview
オブジェクトの配列が含まれます。各 GMSPlaceReview
オブジェクトには属性と作成者属性を含めることができます。アプリにレビューを表示する場合は、帰属または著者の帰属も表示する必要があります。
詳細については、アトリビューションのドキュメントをご覧ください。