このプロダクトまたは機能は、従来版のステータスです。従来版のステータスの詳細については、従来版のサービスと機能をご覧ください。Places API（新規）に移行するには、移行ガイドをご覧ください。

このページは Cloud Translation API によって翻訳されました。

Place Details

欧州経済領域（EEA）のデベロッパー

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

場所の詳細

Place オブジェクトは、特定の場所に関する情報を提供します。Place オブジェクトを取得するには、PlacesClient.fetchPlace() を呼び出します。ID で場所を取得するのガイドをご覧ください。

場所をリクエストする際は、返す場所データを指定する必要があります。これを行うには、返すデータを指定する Place.Field 値のリストを渡します。このリストは、各リクエストの費用に影響するため、重要な考慮事項です。

プレイスデータの結果は空にできないため、データを含むプレイスの結果のみが返されます。たとえば、リクエストされたプレイスに写真がない場合、結果に photos フィールドは含まれません。

次の例では、3 つの Place.Field 値のリストを渡して、リクエストで返されるデータを指定しています。

Kotlin

// Specify the fields to return.
val placeFields = listOf(Place.Field.DISPLAY_NAME, Place.Field.RATING)

Java

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.DISPLAY_NAME, Place.Field.RATING);

Place オブジェクトのデータフィールドにアクセスする

Place オブジェクトを取得したら、オブジェクトのメソッドを使用して、リクエストで指定されたデータフィールドにアクセスします。Place オブジェクトにフィールドがない場合、関連するメソッドは null を返します。以下に、利用可能なメソッドの例をいくつか示します。

getAddress() - 人が読める形式の場所の住所。
getAddressComponents() - この場所の住所コンポーネントの List。これらのコンポーネントは、場所の住所に関する構造化された情報を抽出する目的（場所が所在する都市の特定など）で提供されます。これらのコンポーネントは住所のフォーマットには使用しないでください。代わりに、ローカライズされたフォーマット済み住所を提供する getAddress() を呼び出してください。
getId() - 場所のテキスト表記の ID。プレイス ID について詳しくは、このページの残りの部分をご覧ください。
getLatLng() - 場所の地理的位置。緯度と経度の座標で指定します。
getName() - 場所の名前。
getOpeningHours() - 場所の OpeningHours。OpeningHours.getWeekdayText() を呼び出して、1 週間の各曜日の営業時間を表す文字列のリストを返します。OpeningHours.getPeriods() を呼び出して、getWeekdayText() が提供するデータと同等の詳細情報を含む period オブジェクトのリストを返します。

注: 場所が年中無休の場合は、期間は日曜日の午前 0 時として表され、closeEvent は null になります。
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 を併用する方法については、こちらの動画をご覧ください。

注: このメソッドは非推奨です。代わりに、PlacesClient.isOpen(IsOpenRequest request) を使用してください。詳しくは、オープンステータスを取得するをご覧ください。

例:

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 の初期化について詳しくは、Places API クライアントを初期化するをご覧ください。

営業ステータスを取得する

PlacesClient.isOpen(IsOpenRequest request) メソッドは、呼び出しで指定された時間に基づいて、現在営業しているかどうかを示す IsOpenResponse オブジェクトを返します。

このメソッドは、次のものを含む IsOpenRequest 型の単一の引数を取ります。

Place オブジェクト、またはプレイス ID を指定する文字列。
注: 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.Field.UTC_OFFSET と Place.Field.BUSINESS_STATUS の fetchPlace() への呼び出しに対して、Places Basic Data SKU の料金が発生します。Places の連絡先データ SKU は、Place.Field.CURRENT_OPENING_HOURS と Place.Field.OPENING_HOURS の fetchPlace() の呼び出しに対して課金されます。

次の例では、場所が現在営業中かどうかを判断します。この例では、場所 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 で使用される識別子と同じです。1 つのプレイス ID が参照する場所は 1 つのみですが、1 つの場所が複数のプレイス ID を持つ場合はあります。他にも、ビジネス拠点に新しいプレイス ID が付与される状況があります。たとえば、ビジネスが新しい拠点に移転した場合などです。

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

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

Place Details コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

場所の詳細

Kotlin

Java

Place オブジェクトのデータ フィールドにアクセスする

Kotlin

Java

ID でプレイスを取得する

Kotlin

Java

営業ステータスを取得する

Kotlin

Java

Kotlin

Java

アプリに属性を表示する

プレイス ID について

Place Details

Place オブジェクトのデータフィールドにアクセスする