Places SDK for Android は、場所の名前と住所、緯度と経度の座標で指定された地理的位置、場所の種類（ナイトクラブ、ペットショップ、博物館など）など、場所に関する豊富な情報をアプリに提供します。特定の場所のこうした情報にアクセスするには、場所を一意に識別する不変の 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。プレイス ID について詳しくは、このページの後半をご覧ください。getLatLng()- 場所の地理的位置。緯度と経度の座標で指定されます。getName()– 場所の名前。getOpeningHours()- 場所のOpeningHours。OpeningHours.getWeekdayText()を呼び出すと、曜日ごとの開始時間と終了時間を表す文字列のリストが返されます。OpeningHours.getPeriods()を呼び出すと、getWeekdayText()で提供されるデータと同じ詳細情報を含むperiodオブジェクトのリストが返されます。Placeオブジェクトには、今後 7 日間の場所の営業時間を返すgetCurrentOpeningHours()メソッドと、今後 7 日間の場所のサブの営業時間を返す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_STATUSPlace.Field.CURRENT_OPENING_HOURSPlace.Field.OPENING_HOURSPlace.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 が含まれる場合があります。
詳しくは、プレイス ID の概要をご覧ください。