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

Place Details

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

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 List placeFields = 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)

注: PlacesClient.fetchPlace() は Place Details をすべてサポートしますが、PlacesClient.findCurrentPlace() は Place Details の一部のみをサポートします。findCurrentPlace() でサポートされていないフィールドのリストについては、Places SDK for Android のフィールドのサポートをご覧ください。

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

getAddress() - 人が読める形式の場所の住所。
getAddressComponents() - この場所の住所コンポーネントの List。これらのコンポーネントは、ある場所の市区町村を見つけるなど、場所の住所に関する構造化された情報を抽出するためのものです。住所の書式設定にこれらのコンポーネントを使用しないでください。ローカライズされた住所を提供する getAddress() を呼び出します。
getId() - 場所のテキスト表記の ID。場所 ID について詳しくは、このページの後半をご覧ください。
getLatLng() - 緯度と経度の座標で指定される場所の地理的位置。
getName() - 場所の名前。
getOpeningHours() - 場所の OpeningHours。OpeningHours.getWeekdayText() を呼び出して、曜日ごとの開始時刻と終了時刻を表す文字列のリストを返します。OpeningHours.getPeriods() を呼び出すと、getWeekdayText() から提供されるデータと同等の詳細情報を含む period オブジェクトのリストが返されます。

注: 常に営業している場所は、日曜日の深夜 0 時で表され、closeEvent は null になります。

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

注: このメソッドは非推奨です。代わりに、PlacesClient.isOpen(IsOpenRequest request) を使用してください。詳しくは、営業状況を取得するをご覧ください。

簡単な例:

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 を指定する文字列。
注: 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 をご覧ください。

注: Place.Field.UTC_OFFSET と Place.Field.BUSINESS_STATUS の fetchPlace() の呼び出しに対しては、Basic Data SKU が課金されます。Place.Field.CURRENT_OPENING_HOURS と Place.Field.OPENING_HOURS で fetchPlace() を呼び出した場合、Places Contact Data SKU が課金されます。

次の例では、場所が現在営業しているかどうかを判断します。この例では、場所 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 の概要をご覧ください。