テキスト検索（新版）

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

欧州経済領域（EEA）のデベロッパー

テキスト検索（新版）は、「渋谷 ピザショップ」「表参道 靴店」「123 番地」といった文字列に対して、場所のセットについての情報を返します。テキスト文字列と、その時点で設定済みの地域バイアスをもとに、場所のリストを返すサービスです。

必須パラメータに加えて、テキスト検索（新版）では、オプション パラメータを使用してクエリを絞り込み、より良い結果を得ることができます。

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

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

GMSPlaceSearchByTextRequest オブジェクトは、リクエストの必須パラメータとオプション パラメータをすべて指定します。必須パラメータは次のとおりです。

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

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

Places Swift SDK

let restriction = GMSPlaceRectangularLocationOption(
      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
}

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;
      }
    }
  }
];

テキスト検索のレスポンス

テキスト検索 API は、一致する場所ごとに 1 つの GMSPlace オブジェクトを含む GMSPlace オブジェクトの形式で一致する場所の配列を返します。

営業ステータスを取得する

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

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

  • GMSPlace オブジェクト、またはプレイス ID を指定する文字列。必要なフィールドを含む Place オブジェクトの作成について詳しくは、Place Details をご覧ください。
  • 確認する時間を指定するオプションの NSDate（Obj-C）または Date（Swift）オブジェクト。時刻が指定されていない場合、デフォルトは現在時刻です。
  • レスポンスを処理する GMSPlaceOpenStatusResponseCallback メソッド。
    • >

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

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

isOpenWithRequest レスポンス

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

言語 開いている場合の値 クローズ時の値 ステータスが不明な場合の値
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

isOpenWithRequest の請求

  • GMSPlacePropertyUTCOffsetMinutes フィールドと GMSPlacePropertyBusinessStatus フィールドは、Basic Data SKU で課金されます。その他の営業時間は、Place Details Enterprise SKU で課金されます。
  • 以前のリクエストで GMSPlace オブジェクトにこれらのフィールドがすでに含まれている場合は、再度課金されることはありません。

例: GMSPlaceIsOpenWithRequest リクエストを作成する

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

Places Swift SDK

        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
        }

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
            }
          }];

ページネーション

テキスト検索では、テキスト検索呼び出しの最初のレスポンスで、ページネーション オブジェクト（hasNextPage ブール値）が返されます。次のページが利用可能な場合は、fetchNextPage() 関数を使用して読み込むことができます。

次の例は、次のページが利用可能かどうかを確認してから、ページを読み込む方法を示しています。

Swift

public struct PlaceSearchPagination {
  public var pageSize: Int
  public var hasNextPage: Bool
  public func fetchNextPage() async -> SearchByTextResponse
}

public struct SearchByTextResponse {
  public var pagination: PlaceSearchPagination?
  public var places: [Place]?
  public var error: PlaceError?
}

PlacesClient.swift
public func searchByText(with request: SearchByTextRequest) async -> SearchByTextResponse

let searchByTextRequest = SearchByTextRequest(textQuery: "restaurants",
    placeProperties: [PlaceProperty.displayName],
    locationBias: CircularCoordinateRegion(center: CLLocationCoordinate2D(latitude: 0, longitude: 0), radius: 100))

searchByTextRequest.maxResultCount = 10

var searchByTextResponse = await PlacesClient.shared.searchByText(with: searchByTextRequest)
print("Found \(searchByTextResponse.places.count) places")

searchByTextResponse.pagination.pageSize = 20

// Continue making requests until no more results are found in pagination object
while searchByTextResponse.pagination.hasNextPage {
    searchByTextResponse = await searchByTextResponse.pagination.fetchNextPage()
    print("Found \(searchByTextResponse.places.count) places")
}

Objective-C

GMSPlaceSearchByTextRequest *searchByTextRequest = [[GMSPlaceSearchByTextRequest alloc]
    initWithTextQuery: @"restaurants"
    placeProperties: @[GMSPlacePropertyAll]];

searchByTextRequest.maxResultCount = 10;

__block void (^recursiveCallback)(GMSPlaceSearchByTextResponse *, NSError *);
recursiveCallback = ^(GMSPlaceSearchByTextResponse * response, NSError* error) {
    NSLog(@"Found %d places", response.places.count);
    if (response.pagination.hasNextPage) {
      [response.pagination fetchNextPageWithCompletion:recursiveCallback];
   }
};
[GMSPlacesClient.sharedClient searchByTextWithRequest:searchByTextRequest  
                                           completion:recursiveCallback];

必須パラメータ

GMSPlaceSearchByTextRequest オブジェクトを使用して、検索に必要なパラメータを指定します。

  • フィールド リスト

    返す場所データ プロパティを指定します。返すデータ フィールドを指定する GMSPlace プロパティのリストを渡します。フィールド マスクを省略すると、リクエストはエラーを返します。

    フィールド リストは、不要なデータをリクエストしないようにするための優れた設計手法です。これにより、不要な処理時間と請求料金を回避できます。

    次のフィールドを 1 つ以上指定します。

    • 次のフィールドは、テキスト検索 Essentials ID Only SKU をトリガーします。

      GMSPlacePropertyPlaceID

      フィールドとそれに関連する SKU の一覧については、Place Data Fields（新版）をご覧ください。

    • 次のフィールドは、テキスト検索 Pro SKU をトリガーします。

      GMSPlacePropertyAddressComponents
      GMSPlacePropertyBusinessStatus
      GMSPlacePropertyCoordinate
      GMSPlacePropertyFormattedAddress
      GMSPlacePropertyIconBackgroundColor
      GMSPlacePropertyIconImageURL
      GMSPlacePropertyName
      GMSPlacePropertyPhotos
      GMSPlacePropertyPlusCode
      GMSPlacePropertyTypes
      GMSPlacePropertyUTCOffsetMinutes
      GMSPlacePropertyViewport
      GMSPlacePropertyWheelchairAccessibleEntrance

      フィールドとそれに関連する SKU の一覧については、Place Data Fields（新版）をご覧ください。

    • 次のフィールドは、テキスト検索 Enterprise SKU をトリガーします。

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

      フィールドとそれに関連する SKU の一覧については、Place Data Fields（新版）をご覧ください。

    • 次のフィールドは、テキスト検索 Enterprise Plus SKU をトリガーします。

      GMSPlacePropertyCurbsidePickup
      GMSPlacePropertyDelivery
      GMSPlacePropertyDineIn
      GMSPlacePropertyEditorialSummary
      GMSPlacePropertyReservable
      GMSPlacePropertyReviews
      GMSPlacePropertyServesBeer
      GMSPlacePropertyServesBreakfast
      GMSPlacePropertyServesBrunch
      GMSPlacePropertyServesDinner
      GMSPlacePropertyServesLunch
      GMSPlacePropertyServesVegetarianFood
      GMSPlacePropertyServesWine
      GMSPlacePropertyTakeout

      フィールドとそれに関連する SKU の一覧については、Place Data Fields（新版）をご覧ください。

  • textQuery

    検索するテキスト文字列（「レストラン」、「123 番通り」、「サンフランシスコのおすすめスポット」など）。

オプション パラメータ

GMSPlaceSearchByTextRequest オブジェクトを使用して、検索のオプション パラメータを指定します。

  • includedType

    表 A で定義されている、指定したタイプに一致する場所のみに結果を制限します。指定できるタイプは 1 つだけです。次に例を示します。

    • let request = SearchByTextRequest()
      request.includedType = "bar"
    • let request = SearchByTextRequest()
      request.includedType = "pharmacy"

  • isOpenNow

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

  • isStrictTypeFiltering

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

  • locationBias

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

    locationRestriction または locationBias を指定できますが、両方は指定できません。locationRestriction は、結果がその範囲内になければならない地域を指定するもの、locationBias は、結果がその地域の近くになければならないが、その地域外でもよい地域を指定するものと考えてください。

    地域を長方形の Viewport または円として指定します。

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

      let request = SearchByTextRequest()
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 は、結果がその地域の近くになければならないが、その地域外でもよい地域を指定するものと考えてください。

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

    次に例を示します。

        let request = SearchByTextRequest()
    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」（厳密には「グレート ブリテンおよび北アイルランド連合王国」のエンティティ）です。このパラメータは、適用される法律に基づいて結果に影響する可能性があります。

  • shouldIncludePureServiceAreaBusinesses

    true の場合、検索結果に純粋な非店舗型ビジネスを返します。非店舗型ビジネスとは、客先に出向いてサービスや商品を提供し、ビジネス拠点の住所では接客しないビジネスです。

    次に例を示します。

    Places Swift SDK

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses = true

    Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses: true

    Objective-C

    GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
request.shouldIncludePureServiceAreaBusinesses = YES;

アプリに属性を表示する

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

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

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