テキスト検索（新版）

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 オブジェクトには、帰属情報と作成者の帰属情報を含めることができます。アプリにレビューを表示する場合は、帰属または著者の帰属も表示する必要があります。

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