Text Search は文字列に基づいて、一連の場所についての情報を返します。たとえば、「渋谷 ピザショップ」「表参道 靴店」「123 番地」などです。テキスト文字列と設定された場所のバイアスに一致する場所のリストをレスポンスとして返します。
このサービスは、自動システムであいまいな住所のクエリを行う場合に特に便利です。文字列の住所以外の要素がビジネスと住所に一致する場合があります。あいまいな住所のクエリには、不適切な形式の住所や、お店やサービスの名前などの住所以外の要素を含むリクエストなどがあります。最初の 2 つの例のようなリクエストでは、ロケーション(リージョン、ロケーション制限、ロケーション バイアスなど)が設定されていなければ、結果が返されない場合があります。
「10 High Street, UK」または「123 Main Street, US」 | 英国では複数の「High Street」、米国では複数の「Main Street」を指します。ロケーション制限が設定されていない場合、クエリは望ましい結果を返しません。 |
「東京レストラン チェーン」 | ニューヨークに複数の「チェーン レストラン」がある(番地や通りの名前はない)。 |
「10 High Street, Escher UK」または「123 Main Street, Pleasanton US」 | イギリスのエッシャー市には「ハイ ストリート」が 1 本のみ。米国のカリフォルニア州プレザントン市には「メイン ストリート」が 1 本しかない。 |
「UniqueRestaurantName New York」 | ニューヨークにあるこの名前の施設は 1 つのみであり、区別するのに番地は必要ありません。 |
「東京のピザレストラン」 | このクエリには地域の制限が含まれており、「ピザレストラン」は明確に定義された場所タイプです。複数の結果が返されます。 |
「+1 514-670-8700」 | このクエリには電話番号が含まれています。その電話番号に関連付けられている場所について、複数の結果が返されます。 |
テキスト検索で場所のリストを取得する
Text Search リクエストを作成するには、GMSPlacesClient
searchByTextWithRequest:
を呼び出し、リクエスト パラメータを定義する GMSPlaceSearchByTextRequest
オブジェクトと、レスポンスを処理する GMSPlaceSearchByTextResultCallback
型のコールバック メソッドを渡します。
GMSPlaceSearchByTextRequest
オブジェクトは、リクエストの必須パラメータと省略可能なパラメータをすべて指定します。必須パラメータは次のとおりです。
GMSPlace
オブジェクトで返されるフィールドのリスト。GMSPlaceProperty
で定義され、フィールド マスクとも呼ばれます。フィールド リストで 1 つもフィールドを指定しない場合、またはフィールド リストを省略した場合、この呼び出しはエラーを返します。- テキストクエリ。
このテキスト検索リクエストの例では、レスポンスの GMSPlace
オブジェクトに、検索結果の各 GMSPlace
オブジェクトの場所名とプレイス ID が含まれることを指定しています。また、レスポンスをフィルタリングして、「restaurant」タイプの場所のみを返します。
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 のみ)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
検索結果を、Table 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
の場合、経度の範囲が逆になります(ビューポートは経度線と交差します)。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
オブジェクトには、帰属情報と作成者の帰属情報を含めることができます。アプリにレビューを表示する場合は、帰属または著者の帰属も表示する必要があります。
詳細については、アトリビューションに関するドキュメントをご覧ください。