Place Details

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

Places SDK for Android は、場所の名前と住所、緯度と経度の座標で指定される地理的位置、場所の種類（ナイトクラブ、ペットショップ、博物館など）など、場所に関するさまざまな情報をアプリに提供します。特定の場所についてこの情報にアクセスするには、場所を一意に識別する不変の識別子であるプレイス 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 placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

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

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

  • getAddress() – 人が読める形式の場所の住所。
  • getAddressComponents() - この場所の住所コンポーネントの List。これらのコンポーネントは、場所の住所に関する構造化された情報を抽出する目的で提供されます。たとえば、場所がある都市を見つけることが目的です。これらのコンポーネントは住所の書式設定には使用しないでください。代わりに、ローカライズされた形式の住所を提供する getAddress() を呼び出します。
  • getId() – 場所のテキスト表記の ID。プレイス ID については、このページの残りの部分をご覧ください。
  • getLatLng() - 緯度と経度の座標で指定される場所の地理的位置。
  • getName() – 場所の名前。

  • getOpeningHours() - 場所の OpeningHours。OpeningHours.getWeekdayText() を呼び出して、各曜日の開店時間と閉店時間を表す文字列のリストを返します。OpeningHours.getPeriods() を呼び出すと、getWeekdayText() によって提供されるデータと同じく、詳細情報を含む period オブジェクトのリストが返されます。

    Place オブジェクトには、今後 7 日間の場所の第 2 営業時間を返す 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();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Google Cloud プロジェクトをセットアップするときに、新しい SDK を有効にします。
  2. アクティビティまたはフラグメント内で新しい SDK を初期化します。
  3. リクエストのフィールド リストに Place.Field.NAME を含めます。この値は、場所の名前と言語コードの両方を Place オブジェクトに含めるようにレスポンスを構成します。
  4. PlacesClient.fetchPlace() を呼び出します。 PlacesClient.findCurrentPlace() は言語コード フィールドをサポートしていません。
  5. 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 型の引数を 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 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());
// ...

次の例では、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 と同じです。1 つのプレイス ID が参照できる場所は 1 つだけですが、1 つのプレイスが複数のプレイス ID を持つこともあります。状況によっては、プレイスが新しいプレイス ID を取得する場合もあります。たとえば、ビジネスが新しい場所に移転した場合などが該当します。

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

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