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を呼び出して、その週の毎日の営業時間のローカライズされた文字列のリストを取得します。GMSOpeningHours.Periodsを呼び出すと、weekdayTextから提供されるデータと同等の詳細情報を含むGMSPeriodのリストが返されます。注: 常に営業している場所は、日曜日の深夜 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 では、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 で使用される ID と同じです。
1 つの場所 ID は 1 つの場所のみを参照できますが、1 つの場所が複数の場所 ID を持つことができます。
場所が新しいプレイス ID を取得する場合もあります。たとえば、お店やサービスが新しい場所に移動するケースが考えられます。
場所 ID を指定することによって場所をリクエストすることで、レスポンスで常に同じ場所が受信されるようになります（場所がまだ存在する場合）。ただし、レスポンスには、リクエストとは異なるプレイス ID が含まれている場合があります。
詳しくは、プレイス ID の概要をご覧ください。