Places SDK for Android は、場所の名前と住所、緯度と経度の座標で指定された地理的位置、場所のタイプ(ナイトクラブ、ペットショップ、美術館など)といった場所に関する豊富な情報をアプリに提供します。特定の場所についてこの情報にアクセスするには、プレイス ID(プレイスを一意に識別する固定 ID)を使用できます。
場所の詳細
Place
オブジェクトは、特定の場所に関する情報を提供します。Place
オブジェクトは、次の方法で取得できます。
PlacesClient.findCurrentPlace()
を呼び出します。 現在地を取得するガイドをご覧ください。PlacesClient.fetchPlace()
を呼び出します。 ID で場所を取得するためのガイドをご覧ください。
場所をリクエストする際は、返す場所データを指定する必要があります。これを行うには、返すデータを指定する Place.Field 値のリストを渡します。これは、各リクエストの費用に影響するため、重要な考慮事項です。
プレイスデータの結果は空にはできないため、データを含むプレイスの結果のみが返されます(たとえば、リクエストされたプレイスに写真がない場合、結果に photos
フィールドは含まれません)。
次の例では、3 つの Place.Field 値のリストを渡して、リクエストによって返されるデータを指定します。
Java
// Specify the fields to return. final ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Kotlin
// Specify the fields to return. val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
Place
オブジェクトを取得したら、オブジェクトのメソッドを使用して、リクエストで指定されたデータ フィールドにアクセスします。Place
オブジェクトにフィールドがない場合は、関連するメソッドが null を返します。使用可能なメソッドのいくつかを、以下に示します。
すべてのメソッドの一覧については、Place
API リファレンスをご覧ください。
getAddress()
- 人が読める形式の場所の住所。getAddressComponents()
- この場所の住所コンポーネントのList
。これらのコンポーネントは、ある場所の市区町村を見つけるなど、場所の住所に関する構造化された情報を抽出するためのものです。住所の書式設定にこれらのコンポーネントを使用しないでください。ローカライズされた住所を提供するgetAddress()
を呼び出します。getId()
- 場所のテキスト表記の ID。場所 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 を併用する方法については、こちらの動画をご覧ください。
簡単な例:
Java
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
Kotlin
val name = place.name val address = place.address val location = place.latLng
ID でプレイスを取得する
場所 ID は、場所を一意に識別するテキスト表記の ID です。Places SDK for Android でプレイスの ID を取得するには、Place.getId()
を呼び出します。また、Place Autocomplete サービスは、指定された検索クエリやフィルタに一致する場所ごとにプレイス ID を返します。場所 ID を保存し、それを使用して後で Place
オブジェクトを再度取得できます。
ID で場所を取得するには、PlacesClient.fetchPlace()
を呼び出して、FetchPlaceRequest
を渡します。
API は、Task
で FetchPlaceResponse
を返します。FetchPlaceResponse
には、指定された場所 ID に一致する Place
オブジェクトが格納されます。
次のコード例は、fetchPlace()
を呼び出して、指定された場所の詳細を取得する方法を示しています。
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. } });
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") } }
営業状況を確認する
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()
に渡しています。
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()); // ...
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 } // ...
次の例では、Place
オブジェクトを渡す isOpen()
を呼び出しています。Place
オブジェクトには、有効な場所 ID を含める必要があります。
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()); // ... }); // ...
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 } // ... } // ...
アプリに属性を表示する
アプリに場所情報を表示する場合は、属性も表示する必要があります。アトリビューションに関するドキュメントをご覧ください。
プレイス ID について
Places SDK for Android で使用されるプレイス ID は、Places API で使用される ID と同じです。1 つの場所 ID は 1 つの場所のみを参照できますが、1 つの場所が複数の場所 ID を持つことができます。場所が新しいプレイス ID を取得するケースは他にもあります。これは、ビジネスが新しい場所に移転する場合などに発生することがあります。
場所 ID を指定することによって場所をリクエストすることで、レスポンスで常に同じ場所が受信されるようになります(場所がまだ存在する場合)。ただし、レスポンスには、リクエストとは異なるプレイス ID が含まれている場合があります。
詳しくは、プレイス ID の概要をご覧ください。