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

Place Details

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

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

場所の詳細

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

PlacesClient.fetchPlace() を呼び出す - ID で場所を取得する方法についてのガイドをご覧ください。
PlacesClient.findCurrentPlace() を呼び出す - 現在の場所を取得するためのガイドをご覧ください。
PlacesClient.fetchPlace() はすべてのプレイスデータフィールドに対応していますが、PlacesClient.findCurrentPlace() はプレイスデータフィールドのサブセットのみをサポートしています。findCurrentPlace() でサポートされていないフィールドの一覧については、Places SDK for Android のフィールドのサポートをご覧ください。

場所をリクエストする際は、返す場所データを指定する必要があります。そのためには、返すデータを指定する 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 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 オブジェクトのリストが返されます。

注: 場所が常時営業する場合、時間帯は日曜日の深夜 0 時、closeEvent は null となります。

また、Place オブジェクトには、場所の今後 7 日間の営業時間を返す getCurrentOpeningHours() メソッドと、今後 7 日間の場所のサブの営業時間を返す getSecondaryOpeningHours() メソッドも含まれています。
isOpen() - 場所が現在営業しているかどうかを示すブール値。時間が指定されていない場合、デフォルトは現在になります。Place.Field.UTC_OFFSET と Place.Field.OPENING_HOURS の両方が利用可能な場合にのみ、isOpen が返されます。正確な結果を得るには、元のプレイスリクエストで 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();

バージョン 3.3.0 で追加されたプレイスデータへのアクセス

Places SDK for Android バージョン 3.3.0 では、新しいデータが Place に追加されました。

場所のタイプ: 場所に関連付けられた新しいタイプの値。
クチコミ: 場所について最大 5 件のクチコミ。
名前の言語コード: 場所の名前の言語コードです。

以降のセクションでは、この新しいデータにアクセスする方法について説明します。

注: 新しい SDK は Java の新しい Place データのみをサポートします。

新しい場所のタイプにアクセスする

各場所には、1 つ以上の type 値を関連付けることができます。Places SDK for Android バージョン 3.3.0 には、新しいタイプ値が数多く追加されています。完全なリストについては、展開された場所のタイプをご覧ください。

Places SDK for Android バージョン 3.2.0 以前では、Place.getTypes() メソッドを使用して、場所に関連付けられたタイプの値にアクセスしていました。Place.getTypes() は、Place.Types で定義された列挙型値として型のリストを返します。

Place.getTypes() メソッドは、Places SDK for Android バージョン 3.3.0 で非推奨になりました。非推奨期間中も引き続き使用できますが、代わりに Place.getPlaceTypes() を使用するようにアプリを移行する必要があります。

Place.getPlaceTypes() メソッドは型値を文字列値のリストとして返します。返される値は Places SDK for Android のバージョンによって異なります。

Places SDK for Android（New）: バージョン 3.3.0 で追加されたすべての場所タイプを含む、プレイスタイプ（新規）に示すテーブル A とテーブル B で定義された文字列を返します。
Places SDK for Android: Place.Types で定義された列挙型を返します。バージョン 3.3.0 で追加された新しいタイプは含まれません。

2 つの SDK バージョンの主な違いについては、SDK バージョンを選択するをご覧ください。

場所のクチコミにアクセスする

Places SDK for Android（新規）では、場所のクチコミを含む Review クラスが追加されています。Place オブジェクトには最大 5 つのレビューを含めることができます。

Review クラスには、帰属表示と作成者属性を含めることもできます。アプリにレビューを表示する場合は、帰属または著者の帰属情報も表示する必要があります。詳しくは、レビューを表示するをご覧ください。

Place オブジェクトにクチコミを入力するには、次のことを行う必要があります。

Google Cloud プロジェクトをセットアップするときに、新しい SDK を有効にします。
アクティビティまたはフラグメント内で新しい SDK を初期化します。
Place Details リクエストのフィールドリストに Place.Field.REVIEWS を含めます。
PlacesClient.fetchPlace() を呼び出します。レビューフィールドは PlacesClient.findCurrentPlace() ではサポートされていません。
Place.getReviews() メソッドを使用して、Place オブジェクトの review データフィールドにアクセスします。

場所の名前の言語コードにアクセス

既存の Place.getName() メソッドは、場所の名前を含むテキスト文字列を返します。Place オブジェクトに場所の名前を入力するには、Place Details リクエストのフィールドリストに Place.Field.NAME を含める必要があります。

これで、Place オブジェクトに名前文字列の言語コードが含まれるようになりました。Place オブジェクトに言語コードを設定するには、次のことを行う必要があります。

Google Cloud プロジェクトをセットアップするときに、新しい SDK を有効にします。
アクティビティまたはフラグメント内で新しい SDK を初期化します。
リクエストのフィールドリストに Place.Field.NAME を含めます。この値は、場所の名前と言語コードの両方を Place オブジェクトに含めるようにレスポンスを構成します。
PlacesClient.fetchPlace() を呼び出します。 PlacesClient.findCurrentPlace() は言語コードフィールドをサポートしていません。
Place.getNameLanguageCode() メソッドを使用して、Place オブジェクトの言語コードフィールドにアクセスします。

バージョン 3.3.0 で地域コードを設定する

Places SDK for Android（新規）では、地域コードリクエストパラメータが Place Details に追加されます。リージョンコードは、レスポンスの書式設定に使用されます。 2 文字の CLDR コード値で指定します。このパラメータは、検索結果に対してもバイアスに影響する可能性があります。デフォルト値はありません。リージョンコードを設定するには、新しい SDK を有効にする必要があります。

レスポンスの住所フィールドの国名が地域コードと一致する場合、国コードは住所から省略されます。

ほとんどの CLDR コードは ISO 3166-1 コードと同一ですが、いくつか重要な例外があります。たとえば、英国の ccTLD は「uk」（.co.uk）ですが、ISO 3166-1 コードは「gb」（厳密には「グレートブリテンおよび北アイルランド連合王国」の法人）です。パラメータは、適用される法律に基づいて結果に影響を与える可能性があります。

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

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

次のサンプルでは、場所が現在営業しているかどうかを判定します。この例では、プレイス 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 で使用される識別子です。1 つのプレイス ID で参照できる場所は 1 つのみですが、1 つの場所が複数のプレイス ID を持つ場合もあります。状況によっては、場所が新しいプレイス ID を取得する場合もあります。たとえば、ビジネスが新しい場所に移転した場合が該当します。

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

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

Place Details

場所の詳細

Kotlin

Java

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

Kotlin

Java

バージョン 3.3.0 で追加されたプレイスデータへのアクセス

新しい場所のタイプにアクセスする

場所のクチコミにアクセスする

場所の名前の言語コードにアクセス

バージョン 3.3.0 で地域コードを設定する

ID でプレイスを取得する

Kotlin

Java

営業状況を確認する

Kotlin

Java

Kotlin

Java

アプリに属性を表示する

プレイス ID について

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