Places SDK for iOS は、場所の名前と住所、緯度と経度の座標で指定される地理的位置、場所の種類(ナイトクラブ、ペットショップ、博物館など)など、場所に関する豊富な情報をアプリに提供します。特定の場所のこの情報にアクセスするには、場所を一意に識別する不変の ID であるプレイス ID を使用します。
場所の詳細
GMSPlace
クラスは、特定の場所に関する情報を提供します。GMSPlace
オブジェクトは次の方法で取得できます。
GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:
を呼び出します。現在の場所を取得するためのガイドをご覧ください。GMSPlacesClient fetchPlaceFromPlaceID:
を呼び出し、GMSPlaceField
、プレイス ID、コールバック メソッドを渡します。Place Details リクエストでは、リクエストでフィールドを少なくとも 1 つ指定しなかった場合、またはリクエストのfields
パラメータを省略した場合は、利用可能なフィールドがすべて返され、それに応じて料金が発生します。詳しくは、ID で場所を取得するためのガイドをご覧ください。
場所をリクエストする際は、返す場所データの種類を指定する必要があります。これを行うには、GMSPlaceField
を渡して、返すデータ型を指定します。各リクエストの費用に影響するため、この点は重要です。
プレイスデータの結果を空にすることはできないため、データを含むプレイス結果のみが返されます(たとえば、リクエストされた場所に写真がない場合、photos
フィールドは結果に含まれません)。
次の例では、2 つのフィールド値のリストを渡して、リクエストによって返されるデータを指定します。
Swift
// A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" // Specify the place data types to return. let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) | UInt(GMSPlaceField.placeID.rawValue))
Objective-C
// A hotel in Saigon with an attribution. NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs"; // Specify the place data types to return. GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);
詳しくは、場所のフィールドの概要をご覧ください。場所のデータのリクエストに対する課金方法については、使用量と課金をご覧ください。
GMSPlace
クラスには、以下のプレイスデータを含めることができます。
name
– 場所の名前。editorialSummary
- 場所の簡単な説明を提供します。placeID
– 場所を表すテキスト表記の ID。プレイス ID については、このページの後半をご覧ください。coordinate
- 場所の地理的位置。緯度と経度の座標で指定されます。phoneNumber
– 場所の電話番号(国際電話形式)。formattedAddress
– 人が読める形式のこの場所の住所。ほとんどの場合、この住所は「郵便の宛先」と同一ですイギリスなど一部の国では、ライセンス上の制限があるため実際の郵便の宛先は配信できません。
フォーマット済み住所は、論理的には 1 つ以上の住所コンポーネントで構成されます。たとえば、「111 8th Avenue, New York, NY」という住所は、「111」(番地)、「8th Avenue」(道路名)、「New York」(都市名)、「NY」(アメリカの州名)で構成されています。
フォーマット済み住所は、プログラムで解析しないでください。その代わりに、フォーマット済み住所のフィールドに加えて、API レスポンスに含まれる個々の住所コンポーネントを使用してください。
openingHours
- 場所の営業時間(GMSOpeningHours
で表します)。GMSOpeningHours.weekdayText
を呼び出して、その週の 1 日の営業時間をローカライズした文字列のリストを取得します。GMSOpeningHours.Periods
を呼び出してGMSPeriod
のリストを返します。このリストはweekdayText
が提供するデータと同じです。 注: 場所が常に営業する場合、時間帯は日曜日の深夜 0 時、closeEvent
は null となります。currentOpeningHours
とsecondaryOpeningHours
– 場所のスケジュールの休日や一時的な変更を示すフィールド。addressComponents
- 場所の住所の構成要素を表すGMSAddressComponent
オブジェクトの配列。これらのコンポーネントは、場所の住所に関する構造化された情報を抽出する目的で提供されています。たとえば、その場所がある都市を特定することなどを目的としています。住所の形式には、これらのコンポーネントを使用しないでください。代わりに、ローカライズされた形式の住所を提供するformattedAddress
プロパティを使用してください。addressComponents
配列については、次の点に注意してください。- 住所コンポーネントの配列には、
formattedAddress
よりも多くのコンポーネントが含まれている場合があります。 - この配列には、
formattedAddress
に含まれているもの以外の住所を持つ行政区画がすべて含まれているとは限りません。 - レスポンスの形式は、リクエスト間で同じになるとは限りません。特に、
addressComponents
の数はリクエストされた住所によって異なり、同じ住所でも将来的に変わる可能性があります。コンポーネントは、配列内の位置が変わる場合があります。 コンポーネントのタイプは変わる場合があります。特定のコンポーネントが以降のレスポンスに含まれない場合があります。
- 住所コンポーネントの配列には、
userRatingsTotal
- 場所の評価に含まれるクチコミの数を表します。
GMSPlace
クラスには、次のメンバー関数が含まれています。
-
isOpen
は、openingHours
とUTCOffsetMinutes
と現在の日時に基づいて、場所が特定の時刻に営業しているかどうかを計算します。 isOpenAtDate
は、openingHours
とUTCOffsetMinutes
、および現在の日付と時刻に基づいて、場所が特定の日に営業しているかどうかを計算します。
これらの関数を使用して開始時間や日付を取得する場合、元の fetchPlaceFromPlaceID:
リクエストまたは findPlaceLikelihoodsFromUserLocationWithPlaceFields:
リクエストで GMSPlaceFieldOpeningHours
フィールドと GMSPlaceFieldUTCOffsetMinutes
フィールドの両方を指定する必要があります。これらのフィールドのいずれかが欠けている場合、結果として得られる GMSPlace
オブジェクトに開店の時刻や日付が含まれず、呼び出しは GMSPlaceOpenStatusUnknown
を返します。正確な結果を得るには、元のプレイス リクエストで GMSPlaceFieldBusinessStatus
フィールドと GMSPlaceFieldUTCOffsetMinutes
フィールドをリクエストします。リクエストされていない場合は、ビジネスは営業しているとみなされます。
isOpen
と Place Details を併用する方法については、こちらの動画をご覧ください。特別営業時間を取得
通常の営業時間はopeningHours
から取得できますが、currentOpeningHours
と secondaryOpeningHours
は休日と一時的なスケジュールの変更をサポートします。この特別日の例外営業時間がフィルタされ、必要に応じて表示されます。
Swift
func examineOpeningHours(place: GMSPlace) { // Check if the current opening hours contains a special day that has exceptional hours guard let currentOpeningHours = place.currentOpeningHours else { return } if let specialDays = currentOpeningHours.specialDays { guard !specialDays.isEmpty else { return } if let specialDay = specialDays.filter { $0.isExceptional }.first { // Indicate exceptional hours } } // Check if current opening hours contains a truncated time period let periods = currentOpeningHours.periods if !periods.isEmpty { for period in periods { let open = period.open let close = period.close if let open = open { let date = open.date if open.isTruncated { // Indicate truncated time period } } } } // Check if the place's secondary opening hours indicate when delivery is available let secondaryOpeningHours = place.secondaryOpeningHours guard let hoursType = secondaryOpeningHours.first?.hoursType else { return } if (hoursType == GMSPlaceHoursTypeDelivery) { // Indicate hours where delivery is available } }
Objective-C
- (void)examineOpeningHours:(GMSPlace *) place { // Check if the current opening hours contains a special day that has exceptional hours GMSOpeningHours *currentOpeningHours = place.currentOpeningHours; if (currentOpeningHours != nil) { NSArray<GMSPlaceSpecialDay *> *specialDays = currentOpeningHours.specialDays; if ([specialDays count] != 0) { for (GMSPlaceSpecialDay *specialDay in specialDays) { NSDate *date = specialDay.date; if ([specialDay isExceptional]) { // Indicate exceptional hours } } } } // Check if current opening hours contains a truncated time period NSArray <GMSPeriod *> * periods = currentOpeningHours.periods; if ([periods count] != 0) { for (GMSPeriod * period in periods) { GMSTimeOfWeek *open = period.open; GMSTimeOfWeek *close = period.close; if (open) { if ([open isTruncated]) { // Indicate truncated time period } } } } // Check if the place's secondary opening hours indicate when delivery is available GMSOpeningHours *secondaryOpeningHours = place.secondaryOpeningHours; GMSPlaceHoursType hoursType = secondaryOpeningHours.getHoursType; if (hoursType == GMSPlaceHoursTypeDelivery) { // Indicate hours where delivery is available } }
ID でプレイスを取得する
プレイス ID は、場所を一意に識別するテキスト表記の ID です。Places SDK for iOS では、プレイス ID を GMSPlace
オブジェクトから取得できます。プレイス ID を保存しておき、その ID を使って GMSPlace
オブジェクトを再度取得することができます。
ID で場所を取得するには、GMSPlacesClient
fetchPlaceFromPlaceID:
を呼び出して、次のパラメータを渡します。
- プレイス ID を含む文字列。
- 返すデータ型を指定する 1 つ以上の
GMSPlaceField
。 - オートコンプリート クエリを完了するために呼び出しが行われた場合のセッション トークン。それ以外の場合は nil を渡します。
- 結果を処理する
GMSPlaceResultCallback
。
API は指定されたコールバック メソッドを呼び出し、GMSPlace
オブジェクトを渡します。場所が見つからない場合、プレイス オブジェクトは nil になります。
Swift
// A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" // Specify the place data types to return. let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) | UInt(GMSPlaceField.placeID.rawValue))! placesClient?.fetchPlace(fromPlaceID: placeID, placeFields: fields, sessionToken: nil, callback: { (place: GMSPlace?, error: Error?) in if let error = error { print("An error occurred: \(error.localizedDescription)") return } if let place = place { self.lblName?.text = place.name print("The selected place is: \(place.name)") } })
Objective-C
// A hotel in Saigon with an attribution. NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs"; // Specify the place data types to return. GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID); [_placesClient fetchPlaceFromPlaceID:placeID placeFields:fields sessionToken:nil callback:^(GMSPlace * _Nullable place, NSError * _Nullable error) { if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } if (place != nil) { NSLog(@"The selected place is: %@", [place name]); } }];
アプリに属性を表示する
GMSPlacesClient
lookUpPlaceID:callback:
から取得した情報をアプリに表示する場合は、属性も表示する必要があります。詳しくは、アトリビューションに関するドキュメントをご覧ください。
プレイス ID について
Places SDK for iOS で使用されるプレイス ID は、Places API、Places SDK for Android、その他の Google API で使用されている識別子です。
1 つのプレイス ID で参照できる場所は 1 つのみですが、1 つの場所が複数のプレイス ID を持つ場合もあります。
状況によっては、場所が新しいプレイス ID を取得する場合があります。たとえば、お店やサービスが新しい場所に移動するケースが考えられます。
プレイス ID を指定して場所をリクエストすると、レスポンスで常に同じ場所(その場所がまだ存在する場合)が返されます。ただし、レスポンスには、リクエストとは異なるプレイス ID が含まれる場合があります。
詳しくは、プレイス ID の概要をご覧ください。