Nearby Search（新規）

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

Nearby Search（新規）リクエストは、円として指定された検索対象の地域を入力として受け取ります。この円は、円の中心点の緯度と経度の座標と、半径（メートル単位）で定義されます。このリクエストは、指定された検索エリア内の一致する場所のリストを返します。各場所は GMSPlace オブジェクトで表されます。

デフォルトでは、検索エリア内のすべてのタイプの場所がレスポンスに含まれます。必要に応じて、レスポンスに明示的に含める場所タイプまたは除外する場所タイプのリストを指定して、レスポンスをフィルタできます。たとえば、レスポンスに「レストラン」、「ベーカリー」、「カフェ」の種類の場所のみを含めるように指定したり、「学校」の種類の場所をすべて除外したりできます。

Nearby Search（新規）リクエスト

GMSPlacesClient searchNearbyWithRequest: を呼び出して、リクエスト パラメータを定義する GMSPlaceSearchNearbyRequest オブジェクトと、レスポンスを処理する GMSPlaceSearchNearbyResultCallback タイプのコールバック メソッドを渡し、Nearby Search リクエストを実行します。

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

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

この近くの検索リクエストの例では、レスポンスの GMSPlace オブジェクトに、検索結果の各 GMSPlace オブジェクトの場所名（GMSPlacePropertyName）と場所の座標（GMSPlacePropertyCoordinate）が含まれていることを指定しています。また、レスポンスをフィルタして、「レストラン」と「カフェ」のタイプの場所のみを返します。

Places Swift SDK

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Swift

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

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [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().searchNearby(with: request, callback: callback)

Objective-C

// Array to hold the places in the response
_placeResults = [NSArray array];

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

[_placesClient searchNearbyWithRequest:request
  callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
        // Get list of places.
        _placeResults = places;
    }
  }
];

Nearby Search レスポンス

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

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

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

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

  • GMSPlace オブジェクト、またはプレイス ID を指定する文字列。必要なフィールドを使用して Place オブジェクトを作成する方法については、場所の詳細をご覧ください。
  • チェックする時刻を指定する 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
            }
          }];

必須パラメータ

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

  • フィールドリスト

    場所の詳細をリクエストする際は、場所の GMSPlace オブジェクトで、返すデータをフィールドマスクとして指定する必要があります。フィールド マスクを定義するには、値の配列を GMSPlaceProperty から GMSPlaceSearchNearbyRequest オブジェクトに渡します。フィールド マスキングは、不要なデータをリクエストしないようにするための優れた設計手法です。これにより、不要な処理時間と課金が発生するのを防ぐことができます。

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

    • 次のフィールドは、Nearby Search Pro SKU をトリガーします。

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

    • 次のフィールドは、Nearby Search Enterprise SKU をトリガーします。

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • 次のフィールドは、Nearby Search Enterprise Plus SKU をトリガーします。

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

    次の例では、2 つのフィールド値のリストを渡して、リクエストによって返される GMSPlace オブジェクトに name フィールドと placeID フィールドが含まれていることを指定します。

    Places Swift SDK

    // Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]

    Swift

    // Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]

    Objective-C

    // Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];

  • locationRestriction

    検索対象領域を円として定義する GMSPlaceLocationRestriction オブジェクト。中心点と半径（メートル単位）で定義します。半径は 0.0 ～ 50000.0 の範囲で指定してください。デフォルトの半径は 0.0 です。リクエストで 0.0 より大きい値に設定する必要があります。

オプション パラメータ

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

  • includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

    検索結果のフィルタに使用するタイプ表 A のタイプから、タイプのリストを指定できます。各タイプの制限カテゴリで最大 50 個のタイプを指定できます。

    プレイスには、関連付けられている表 A のタイプから1 つのプライマリ タイプのみを指定できます。たとえば、プライマリ タイプは "mexican_restaurant" または "steak_house" です。includedPrimaryTypes と excludedPrimaryTypes を使用して、場所のプライマリ タイプで結果をフィルタします。

    場所には、表 A のタイプから複数のタイプ値を関連付けることもできます。たとえば、レストランのタイプは "seafood_restaurant"、"restaurant"、"food"、"point_of_interest"、"establishment" のいずれかになります。includedTypes と excludedTypes を使用して、場所に関連付けられたタイプのリストで結果をフィルタします。

    "restaurant" や "hotel" などの一般的なプライマリ タイプを指定すると、指定したプライマリ タイプよりも具体的なプライマリ タイプの場所がレスポンスに含まれることがあります。たとえば、プライマリ タイプ "restaurant" を含めるように指定します。レスポンスには、"restaurant" をメインタイプとする場所が含まれますが、"chinese_restaurant" や "seafood_restaurant" など、より具体的なメインタイプを持つ場所も含まれます。

    検索で複数の種類の制限が指定されている場合、すべての制限を満たす場所のみが返されます。たとえば、{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]} を指定すると、返される場所は "restaurant" 関連のサービスを提供しますが、主に "steak_house" として機能しません。

    includedTypes

    表 A の検索対象の場所タイプのリスト。このパラメータを省略すると、すべてのタイプの場所が返されます。

    excludedTypes

    検索から除外する表 A のプレイスタイプのリスト。

    リクエストで includedTypes（"school" など）と excludedTypes（"primary_school" など）の両方を指定すると、"school" に分類される場所がレスポンスに含まれますが、"primary_school" に分類される場所は含まれません。レスポンスには、includedTypes の少なくとも 1 つと excludedTypes のいずれにも一致しない場所が含まれます。

    includedTypes と excludedTypes の両方に出現する型など、競合する型がある場合、INVALID_REQUEST エラーが返されます。

    includedPrimaryTypes

    検索に含める 表 A の主要なプレイスタイプのリスト。

    excludedPrimaryTypes

    検索から除外する表 A のプライマリ プレイスタイプのリスト。

    includedPrimaryTypes と excludedPrimaryTypes の両方に存在するタイプなど、競合するプライマリ タイプがある場合、INVALID_ARGUMENT エラーが返されます。

  • maxResultCount

    返される場所の結果の最大数を指定します。1 ～ 20（デフォルト）の値にする必要があります。

  • rankPreference

    使用するランキングのタイプ。このパラメータを省略すると、検索結果は人気度でランク付けされます。次のいずれかになります。

    • .popularity（デフォルト）人気度に基づいて結果を並べ替えます。
    • .distance 指定された場所からの距離に応じて結果を昇順で並べ替えます。

  • regionCode

    レスポンスのフォーマットに使用される地域コード。 2 文字の CLDR コード値で指定します。デフォルト値はありません。

    レスポンスの formattedAddress フィールドの国名が regionCode と一致する場合、国コードは formattedAddress から省略されます。このパラメータは、国名が常に含まれる adrFormatAddress と、国名が含まれない shortFormattedAddress には影響しません。

    ほとんどの CLDR コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」（.co.uk）ですが、ISO 3166-1 コードは「gb」です（技術的には「グレート ブリテンおよび北アイルランド連合王国」のエンティティ用）。このパラメータは、適用される法律に基づいて結果に影響する可能性があります。

アプリに属性を表示する

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

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

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