テキスト検索（新版）

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

この機能を使用するには、Places API の次世代版である Places API（新規）を有効にする必要があります。詳細については、API を有効にするをご覧ください。

Text Search は、文字列に基づいてプレイスのセットに関する情報を返します。たとえば、「渋谷 ピザショップ」「表参道 靴店」「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」	英国の Escher 市には「High Street」が 1 つしかなく、米国の Pleasanton CA 市には「Main Street」が 1 つしかありません。
「UniqueRestaurantName New York」	ニューヨークにこの名前の施設は 1 か所のみで、区別するために住所は必要ありません。
「ニューヨークのピザレストラン」	このクエリには場所の制限が含まれており、「ピザレストラン」は明確に定義された場所のタイプです。複数の結果が返されます。
「[phone]」	このクエリには電話番号が含まれています。その電話番号に関連付けられている場所の複数の結果が返されます。 注: 電話番号で検索する場合は、国コードに続けてスペースを挿入し、regionCode パラメータを国コードに対応するように設定すると、より正確な結果が得られます。電話番号の形式は国によって異なり、API はこれらの異なる形式の結果を返そうとします。

テキスト検索で場所のリストを取得する

GMSPlacesClient searchByTextWithRequest: を呼び出してテキスト検索リクエストを行い、リクエスト パラメータを定義する GMSPlaceSearchByTextRequest オブジェクトと、レスポンスを処理する GMSPlaceSearchByTextResultCallback 型のコールバック メソッドを渡します。

GMSPlaceSearchByTextRequest オブジェクトには、リクエストのすべての必須パラメータと省略可能なパラメータを指定します。必須パラメータには次のものがあります。

• GMSPlace オブジェクトで返されるフィールドのリスト。GMSPlaceProperty で定義されているフィールド マスクとも呼ばれます。フィールドリストでフィールドを 1 つ以上指定しない場合、またはフィールドリストを省略した場合、呼び出しはエラーを返します。
• テキスト クエリ。

このテキスト検索リクエストの例では、レスポンスの GMSPlace オブジェクトに、検索結果の各 GMSPlace オブジェクトのプレイス名とプレイス ID が含まれるように指定しています。また、レスポンスをフィルタして、「レストラン」タイプの場所のみを返します。

Swift

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

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
  }
  placeResults = results
}

GMSPlacesClient.shared().searchByText(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.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.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 (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

iOS 向け Places Swift SDK（プレビュー）

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 オブジェクトのフィールドを空にすることはできません。たとえば、フィールドリストに GMSPlacePropertyPhotos が含まれており、レスポンスで photos フィールドをリクエストし、レスポンスの photos フィールドが空の場合、レスポンスの GMSPlace オブジェクトから除外されます。

オープン ステータスを取得する

GMSPlacesClient オブジェクトには、isOpenWithRequest（Swift では isOpenRequest、GooglePlacesSwift では isPlaceOpenRequest）というメンバー関数があります。この関数は、呼び出しで指定された時刻に基づいて、プレイスが現在営業中かどうかを示すレスポンスを返します。

注: 非推奨の GMSPlace isOpen: 関数と GMSPlace isOpenAtDate: 関数は不正確になる可能性があり、Places API（新規）では使用できません。

このメソッドは、次の内容を含む GMSPlaceIsOpenWithRequest 型の単一の引数を取ります。

• GMSPlace オブジェクト、またはプレイス ID を指定する文字列。必要なフィールドを使用して Place オブジェクトを作成する方法については、Place の詳細をご覧ください。
  
  注: Place オブジェクトには有効なプレイス ID を含める必要があります。
• チェックする時刻を指定する NSDate（Obj-C）または Date（Swift）オブジェクト（省略可）。時刻が指定されていない場合、デフォルトは現在時刻です。
• レスポンスを処理する GMSPlaceOpenStatusResponseCallback メソッド。
>

GMSPlaceIsOpenWithRequest メソッドでは、GMSPlace オブジェクトに次のフィールドを設定する必要があります。

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

これらのフィールドが Place オブジェクトで指定されていない場合、またはプレイス ID を渡した場合、このメソッドは GMSPlacesClient GMSFetchPlaceRequest: を使用してこれらのフィールドを取得します。

isOpenWithRequest レスポンス

isOpenWithRequest は、ビジネスが営業中か閉店中か、ステータスが不明かどうかを示す status という名前のブール値を含む GMSPlaceIsOpenResponse オブジェクトを返します。

言語	オープンの場合の値	閉店時の値	ステータスが不明な場合の値
Swift	.open	.closed	.unknown
Objective-C	GMSPlaceOpenStatusOpen	GMSPlaceOpenStatusClosed	GMSPlaceOpenStatusUnknown
GooglePlacesSwift（プレビュー版）	true	false	nil

isOpenWithRequest の請求

• GMSPlacePropertyUTCOffsetMinutes フィールドと GMSPlacePropertyBusinessStatus フィールドは、Basic Data SKU で課金されます。残りの営業時間は、Place Details (Advanced) SKU で課金されます。
• GMSPlace オブジェクトに以前のリクエストのこれらのフィールドがすでに存在する場合、再度請求されることはありません。
• 警告 GMSPlace オブジェクトにこれらのフィールドがない場合、Basic Data SKU の料金が再度請求されます。残りの営業時間は、Place Details (Advanced) SKU で課金されます。プロジェクトで isOpenWithRequest を使用する場合は、必要なプレイスの詳細を取得することをおすすめします。

例: GMSPlaceIsOpenWithRequest リクエストを実行する

次の例は、既存の GMSPlace オブジェクト内で GMSPlaceIsOpenWithRequest を初期化する方法を示しています。

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }
        

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];
  
          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }
  
            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];
          

GooglePlacesSwift

          let isOpenRequest = IsPlaceOpenRequest(place: place)
          switch await placesClient.isPlaceOpen(with: isOpenRequest) {
            case .success(let isOpenResponse):
              switch isOpenResponse.status {
                case true:
                  // Handle open
                case false:
                  // Handle closed
                case nil:
                  // Handle unknown
            case .failure(let placesError):
              // Handle error
          }
          

必須パラメータ

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"
  注: 表 B の値はレスポンスでのみ返されます。表 B の値をフィルタとして使用することはできません。

• isOpenNow

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

• isStrictTypeFiltering

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

• locationBias

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

  locationRestriction または locationBias を指定できますが、両方は指定できません。locationRestriction は、結果が含まれる必要があるリージョンを指定すると考えてください。locationBias は、結果が近い必要があるリージョンを指定すると考えてください。ただし、そのリージョンの外部にあってもかまいません。

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

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

  • 円は、中心点と半径（メートル単位）で定義されます。半径は 0.0 ～ 50000.0 の範囲で指定する必要があります。デフォルトの半径は 0.0 です。次に例を示します。

    request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.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 は、結果が近い必要があるリージョンを指定すると考えてください。ただし、そのリージョンの外部にあってもかまいません。

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

• 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 つ以上の値の配列を指定します。

  注: PRICE_LEVEL_FREE はリクエストでは使用できません。レスポンスの入力にのみ使用されます。

  次に例を示します。

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

アプリに属性を表示する

アプリに GMSPlacesClient から取得した情報（写真やクチコミなど）を表示する場合、アプリには必要な帰属情報も表示する必要があります。

たとえば、GMSPlacesClient オブジェクトの reviews プロパティには、最大 5 つの GMSPlaceReview オブジェクトの配列が含まれます。各 GMSPlaceReview オブジェクトには、アトリビューションと著者アトリビューションを含めることができます。アプリにクチコミを表示する場合は、帰属情報または投稿者の帰属情報も表示する必要があります。

詳細については、アトリビューションに関するドキュメントをご覧ください。