Place Details（新規）

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

iOS 向け Places SDK（新規）は、場所の名前や住所、緯度/経度座標で指定された地理的位置、場所の種類（ナイトクラブ、ペットショップ、美術館など）など、場所に関する豊富な情報をアプリに提供します。特定の場所に関するこの情報にアクセスするには、プレイス ID を使用します。プレイス ID は、場所を一意に識別する安定した ID です。

Place Details を取得する

GMSPlace クラスには、プレイス データ フィールド（新規）に表示されるすべてのデータフィールドなど、特定のプレイスに関する情報が含まれています。GMSPlacesClient fetchPlaceWithRequest: を呼び出し、GMSFetchPlaceRequest オブジェクトと GMSPlaceResultCallback タイプのコールバック メソッドを渡して、GMSPlace オブジェクトを取得します。

GMSFetchPlaceRequest オブジェクトは、次の項目を指定します。

  • （必須）プレイス ID: Google プレイスのデータベースと Google マップで、特定の場所を一意に識別する ID です。
  • （必須）GMSPlace オブジェクトで返されるフィールドのリスト。GMSPlaceProperty で定義されているフィールド マスクとも呼ばれます。フィールドリストでフィールドを 1 つ以上指定しない場合、またはフィールドリストを省略した場合、呼び出しはエラーを返します。
  • （省略可）レスポンスの形式設定に使用される地域コード。
  • （省略可）Autocomplete（新規）セッションの終了に使用されるセッション トークン。

Place Details リクエストを行う

この例では、次のパラメータを渡して ID でプレイスを取得します。

  • ChIJV4k8_9UodTERU5KXbkYpSYs の Place ID。
  • 場所の名前とウェブサイト URL を返すように指定したフィールドリスト。
  • 結果を処理する GMSPlaceResultCallback。

API は、指定されたコールバック メソッドを呼び出し、GMSPlace オブジェクトを渡します。場所が見つからない場合、プレイス オブジェクトは nil になります。

Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

// Create the GMSFetchPlaceRequest object.
let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

client.fetchPlace(with: fetchPlaceRequest, callback: {
  (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name))")
})

Objective-C

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite];

// Create the GMSFetchPlaceRequest object.
GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil];

[placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
    NSLog(@"Place Found: %@", place.name);
    NSLog(@"The place URL: %@", place.website);
  }
}];

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

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.name, .website]
)
switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  // Handle place
case .failure(let placesError):
  // Handle error
}

Place Details レスポンス

Place Details は、場所の詳細を含む GMSPlace オブジェクトを返します。GMSPlace オブジェクトに入力されるのは、フィールドリストで指定されたフィールドのみです。

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

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

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

  • GMSPlace オブジェクト、またはプレイス ID を指定する文字列。必要なフィールドを使用して Place オブジェクトを作成する方法については、Place の詳細をご覧ください。
  • チェックする時刻を指定する 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 オブジェクトに以前のリクエストのこれらのフィールドがすでに存在する場合、再度請求されることはありません。

例: 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
          }

必須パラメータ

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

プレイス ID

Places SDK for iOS で使用されるプレイス ID は、Places API、Places SDK for Android、その他の Google API で使用される ID と同じです。各プレイス ID が参照する場所は 1 つのみですが、1 つの場所が複数のプレイス ID を持つ場合はあります。

場所に新しいプレイス ID が割り当てられる場合があります。たとえば、お店やサービスが新しい場所に移動するケースが考えられます。

場所 ID を指定して場所をリクエストすると、レスポンスで常に同じ場所が返されます（場所がまだ存在する場合）。ただし、レスポンスには、リクエストの場所 ID とは異なる場所 ID が含まれている場合があります。

フィールドリスト

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

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

  • 次のフィールドは、Place Details (ID Only) SKU をトリガーします。

    GMSPlacePropertyPlaceID、GMSPlacePropertyName、GMSPlacePropertyPhotos

  • 次のフィールドは、Place Details (Location Only) SKU をトリガーします。

    GMSPlacePropertyAddressComponents、GMSPlacePropertyFormattedAddress、GMSPlacePropertyCoordinate、GMSPlacePropertyPlusCode、GMSPlacePropertyTypes、GMSPlacePropertyViewport

  • 次のフィールドは、Place Details (Basic) SKU をトリガーします。

    GMSPlacePropertyBusinessStatus、GMSPlacePropertyIconBackgroundColor、GMSPlacePropertyIconImageURL、GMSPlacePropertyUTCOffsetMinutes、GMSPlacePropertyWheelchairAccessibleEntrance

  • 次のフィールドは、Place Details (Advanced) SKU をトリガーします。

    GMSPlacePropertyCurrentOpeningHours、GMSPlacePropertySecondaryOpeningHours、GMSPlacePropertyPhoneNumber、GMSPlacePropertyPriceLevel、GMSPlacePropertyRating、GMSPlacePropertyOpeningHours、GMSPlacePropertyUserRatingsTotal、GMSPlacePropertyWebsite

  • 次のフィールドは、Place Details (Preferred) SKU をトリガーします。

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

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

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

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

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

オプション パラメータ

オプション パラメータを指定するには、GMSFetchPlaceRequest オブジェクトを使用します。

regionCode

レスポンスの形式設定に使用される地域コード。 2 文字の CLDR コード値として指定します。このパラメータは、検索結果にバイアス効果をもたらす可能性があります。デフォルト値はありません。

レスポンスの住所フィールドの国名が地域コードと一致する場合、住所から国コードが省略されます。

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

sessionToken

セッション トークンは、Autocomplete（新規）の呼び出しを「セッション」として追跡するユーザー作成の文字列です。Autocomplete（新規）は、セッション トークンを使用して、予測入力検索でのユーザーのクエリと場所の選択フェーズを、請求処理のために個別のセッションにグループ化します。セッション トークンは、Autocomplete（新規）呼び出しに続く Place Details（新規）呼び出しに渡されます。詳細については、セッション トークンをご覧ください。

アプリに属性を表示する

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

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

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