Nearby Search（新規）

プラットフォームを選択: Android iOS JavaScript ウェブサービス
欧州経済領域（EEA）のデベロッパー

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

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

Nearby Search（新規）リクエスト

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

GMSPlaceSearchNearbyRequest オブジェクトは、リクエストのすべての必須パラメータと省略可パラメータを指定します。必須パラメータは次のとおりです。

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

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

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 オブジェクトを使用して、検索に必要なパラメータを指定します。

  • フィールド リスト

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

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