Places SDK for Android は、場所の名前や住所、緯度と経度の座標で指定された地理的位置、場所の種類(ナイトクラブ、ペットショップ、美術館など)など、場所に関する豊富な情報をアプリに提供します。特定の場所の情報にアクセスするには、プレイス ID を使用します。プレイス ID は、場所を一意に識別する固定の ID です。
場所の詳細
Place
オブジェクトは、特定の場所に関する情報を提供します。Place
オブジェクトは、次の方法で取得します。
PlacesClient.fetchPlace()
を呼び出す - ID で場所を取得するためのガイドをご覧ください。PlacesClient.findCurrentPlace()
を呼び出す - 現在の場所を取得するためのガイドをご覧ください。
場所をリクエストするときは、返す場所データを指定する必要があります。そのためには、返すデータを指定する Place.Field 値のリストを渡します。このリストは、各リクエストの費用に影響するため、重要な考慮事項です。
プレイスデータの結果を空にすることはできないため、データが含まれるプレイスの結果のみが返されます(たとえば、リクエストされた場所に写真がない場合、photos
フィールドは結果に含まれません)。
次の例では、3 つの Place.Field 値のリストを渡して、リクエストによって返されるデータを指定しています。
Kotlin
// Specify the fields to return. val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
Java
// Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
プレイス オブジェクトのデータ フィールドにアクセスする
Place
オブジェクトを取得したら、オブジェクトのメソッドを使用して、リクエストで指定されたデータ フィールドにアクセスします。このフィールドが Place
オブジェクトに欠落している場合、関連するメソッドは null を返します。以下に、利用可能な方法の例を示します。すべてのメソッドの一覧については、Place
API リファレンスをご覧ください。
getAddress()
- 人が読める形式の場所の住所。getAddressComponents()
- この場所の住所コンポーネントのList
。これらのコンポーネントは、場所の住所に関する構造化された情報を抽出する目的で提供されます。たとえば、場所がある都市の検索などです。住所の書式設定にこれらのコンポーネントは使用せず、代わりにgetAddress()
を呼び出して、ローカライズされた書式設定済みの住所を提供します。getId()
– 場所のテキスト識別子。プレイス ID の詳細については、このページの残りの部分をご覧ください。getLatLng()
- 場所の地理的位置。緯度と経度の座標で指定されます。getName()
- 場所の名前。getOpeningHours()
- 場所のOpeningHours
。OpeningHours.getWeekdayText()
を呼び出すと、各曜日の開店時間と閉店時間を表す文字列のリストが返されます。OpeningHours.getPeriods()
を呼び出すと、getWeekdayText()
で提供されるデータと同等の詳細情報を含むperiod
オブジェクトのリストが返されます。Place
オブジェクトには、次の 7 日間の場所の営業時間を返すgetCurrentOpeningHours()
メソッドと、次の 7 日間の場所の第 2 の営業時間を返すgetSecondaryOpeningHours()
も含まれています。isOpen()
- その場所が現在営業中かどうかを示すブール値。時間が指定されていない場合、デフォルトは現在です。isOpen
は、Place.Field.UTC_OFFSET
とPlace.Field.OPENING_HOURS
の両方が使用可能な場合にのみ返されます。正確な結果を得るには、元のプレイス リクエストでPlace.Field.BUSINESS_STATUS
フィールドとPlace.Field.UTC_OFFSET
フィールドをリクエストします。リクエストがない場合は、営業しているとみなされます。isOpen
を Place Details で使用する方法については、こちらの動画をご覧ください。
簡単な例:
Kotlin
val name = place.name val address = place.address val location = place.latLng
Java
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
ID でプレイスを取得する
プレイス ID は、場所を一意に識別するテキスト表記の ID です。Places SDK for Android では、Place.getId()
を呼び出して場所の ID を取得できます。
Place Autocomplete サービスは、指定した検索クエリとフィルタに一致する各場所のプレイス ID も返します。プレイス ID を保存しておき、その ID を使って後で Place
オブジェクトを再度取得できます。
ID で場所を取得するには、PlacesClient.fetchPlace()
を呼び出して FetchPlaceRequest
を渡します。
API は、Task
で FetchPlaceResponse
を返します。FetchPlaceResponse
には、指定されたプレイス ID に一致する Place
オブジェクトが含まれます。
次のコード例は、fetchPlace()
を呼び出して、指定された場所の詳細を取得する方法を示しています。
Kotlin
// Define a Place ID. val placeId = "INSERT_PLACE_ID_HERE" // Specify the fields to return. val placeFields = listOf(Place.Field.ID, Place.Field.NAME) // Construct a request object, passing the place ID and fields array. val request = FetchPlaceRequest.newInstance(placeId, placeFields) placesClient.fetchPlace(request) .addOnSuccessListener { response: FetchPlaceResponse -> val place = response.place Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}") }.addOnFailureListener { exception: Exception -> if (exception is ApiException) { Log.e(TAG, "Place not found: ${exception.message}") val statusCode = exception.statusCode TODO("Handle error with given status code") } }
Java
// Define a Place ID. final String placeId = "INSERT_PLACE_ID_HERE"; // Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // Construct a request object, passing the place ID and fields array. final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); placesClient.fetchPlace(request).addOnSuccessListener((response) -> { Place place = response.getPlace(); Log.i(TAG, "Place found: " + place.getName()); }).addOnFailureListener((exception) -> { if (exception instanceof ApiException) { final ApiException apiException = (ApiException) exception; Log.e(TAG, "Place not found: " + exception.getMessage()); final int statusCode = apiException.getStatusCode(); // TODO: Handle error with given status code. } });
営業状況を確認する
PlacesClient.isOpen(IsOpenRequest request)
メソッドは、呼び出しで指定された時間に基づいて、その場所が現在営業中かどうかを示す IsOpenResponse
オブジェクトを返します。
このメソッドは、以下を含む IsOpenRequest
型の単一の引数を取ります。
Place
オブジェクト、またはプレイス ID を指定する文字列。- 1970-01-01T00:00:00Z からの時間をミリ秒単位で指定するオプションの時刻値。時間が指定されていない場合、デフォルトは現在です。
このメソッドを使用するには、次のフィールドが Place
オブジェクトに存在する必要があります。
Place.Field.BUSINESS_STATUS
Place.Field.CURRENT_OPENING_HOURS
Place.Field.OPENING_HOURS
Place.Field.UTC_OFFSET
これらのフィールドが Place
オブジェクトで提供されていない場合や、プレイス ID を渡した場合、メソッドは PlacesClient.fetchPlace()
を使用してフィールドを取得します。必要なフィールドを含む Place オブジェクトの作成について詳しくは、Place Details をご覧ください。
次の例では、場所が現在営業中かどうかを判断します。この例では、プレイス ID のみを isOpen()
に渡しています。
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk" val request: IsOpenRequest = try { IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request) isOpenTask.addOnSuccessListener { response -> val isOpen = response.isOpen } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"; IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest); placeTask.addOnSuccessListener( (response) -> isOpen = response.isOpen()); // ...
次の例では、isOpen()
を呼び出して Place
オブジェクトを渡します。Place
オブジェクトには、有効なプレイス ID を含める必要があります。
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() var place: Place val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk" // Specify the required fields for an isOpen request. val placeFields: List<Place.Field> = listOf( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.UTC_OFFSET ) val placeRequest: FetchPlaceRequest = FetchPlaceRequest.newInstance(placeId, placeFields) val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest) placeTask.addOnSuccessListener { placeResponse -> place = placeResponse.place val isOpenRequest: IsOpenRequest = try { IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return@addOnSuccessListener } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest) isOpenTask.addOnSuccessListener { isOpenResponse -> val isOpen = isOpenResponse.isOpen } // ... } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"; // Specify the required fields for an isOpen request. List<Place.Field> placeFields = new ArrayList<>(Arrays.asList( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.UTC_OFFSET )); FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request); placeTask.addOnSuccessListener( (placeResponse) -> { Place place = placeResponse.getPlace(); IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest); isOpenTask.addOnSuccessListener( (isOpenResponse) -> isOpen = isOpenResponse.isOpen()); // ... }); // ...
アプリに属性を表示する
アプリに場所のクチコミなどの場所情報を表示する場合は、属性も表示する必要があります。詳細については、アトリビューションをご覧ください。
プレイス ID について
Places SDK for Android で使用されるプレイス ID は、Places API で使用されている ID と同じです。1 つのプレイス ID が参照できる場所は 1 つのみですが、1 つの場所に複数のプレイス ID が存在することがあります。他の状況では、プレイスが新しいプレイス ID を取得する原因となる場合があります。たとえば、ビジネスが新しい場所に移転した場合などに発生する可能性があります。
プレイス ID を指定して場所をリクエストすると、(場所がまだ存在している場合に)常に同じ場所がレスポンスで確実に返されるようになります。ただし、レスポンスには、リクエストとは異なるプレイス ID が含まれる場合があります。
詳しくは、プレイス ID の概要をご覧ください。