Places SDK for iOS は、場所の名前や住所、緯度と経度の座標で指定された地理的位置、場所のタイプ(ナイトクラブ、ペットショップ、博物館など)など、場所に関する豊富な情報を提供します。特定の場所についてこの情報にアクセスするには、場所 ID を使用します。場所 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
- 場所の名前。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
を呼び出すと、weekdayText
によって提供されるデータと同等の詳細な情報を含むGMSPeriod
のリストが返されます。注: 常に営業している場所は、日曜日の深夜 0 時、closeEvent
は null で表されます。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 を併用する方法については、こちらの動画をご覧ください。
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 と同じです。
各場所 ID は 1 つの場所のみを参照できますが、1 つの場所には複数の場所 ID を含めることができます。
ある場所が新しいプレイス ID を取得する場合があります。たとえば、お店やサービスが新しい場所に移動するケースが考えられます。
場所 ID を指定して場所をリクエストすると、(その場所がまだ存在する場合)常に同じ場所を受け取ることが保証されます。ただし、レスポンスに、リクエストと異なるプレイス ID が含まれていることがあります。
詳しくは、場所 ID の概要をご覧ください。