Place Details

プラットフォームを選択: Android iOS JavaScript ウェブサービス

Places SDK for Android は、場所の名前や住所、緯度/経度座標で指定された地理的位置、場所の種類（ナイトクラブ、ペットショップ、美術館など）など、場所に関する豊富な情報をアプリに提供します。特定の場所に関するこの情報にアクセスするには、プレイス ID を使用します。プレイス ID は、場所を一意に識別する安定した識別子です。

場所の詳細

Place オブジェクトは、特定の場所に関する情報を提供します。Place オブジェクトは、次の方法で取得できます。

場所をリクエストする際は、返す場所データを指定する必要があります。これを行うには、返すデータを指定する 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 を返します。使用可能なメソッドの例を以下に示します。

  • 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 を併用する方法については、こちらの動画をご覧ください。

例:

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 でプレイスを取得するには、FetchPlaceRequest を渡して PlacesClient.fetchPlace() を呼び出します。

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 型の引数を 1 つ受け取ります。

  • 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 オブジェクトを作成する方法については、場所の詳細をご覧ください。

次の例では、場所が現在営業中かどうかを判断します。この例では、場所 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());
// ...

次の例は、Place オブジェクトを渡して isOpen() を呼び出す方法を示しています。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 と同じです。各プレイス ID が参照できるプレイスは 1 つだけですが、1 つのプレイスに複数のプレイス ID を割り当てることもできます。プレイスに新しいプレイス ID が割り当てられる原因は他にもあります。たとえば、ビジネスが新しい場所に移転した場合に発生することがあります。

場所 ID を指定して場所をリクエストすると、レスポンスで常に同じ場所が返されます（場所がまだ存在する場合）。ただし、レスポンスには、リクエストの場所 ID とは異なる場所 ID が含まれている場合があります。

詳しくは、プレイス ID の概要をご覧ください。