Place Details

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

Places SDK for Android は、場所の名前や住所、緯度と経度の座標で指定された地理的位置、場所の種類（ナイトクラブ、ペットショップ、美術館など）など、場所に関する豊富な情報をアプリに提供します。特定の場所の情報にアクセスするには、プレイス ID を使用します。プレイス 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<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
  

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

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

• getAddress() - 人が読める形式の場所の住所。
• getAddressComponents() - この場所の住所コンポーネントの List。これらのコンポーネントは、場所の住所に関する構造化された情報を抽出する目的で提供されます。たとえば、場所がある都市の検索などです。住所の書式設定にこれらのコンポーネントは使用せず、代わりに getAddress() を呼び出して、ローカライズされた書式設定済みの住所を提供します。
• getId() – 場所のテキスト識別子。プレイス 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) を使用してください。詳しくは、営業ステータスを取得するをご覧ください。

簡単な例:

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

CancellationToken を使用すると、任意のリクエスト クラス（FetchPlaceRequest など）に対するリクエストのキャンセルを試行できます。キャンセルはベスト エフォート ベースで行われます。キャンセル リクエストが発行されると、レスポンスは返されません。キャンセル トークンを発行しても、特定のリクエストがキャンセルされるとは限りません。レスポンスが返されなくても、リクエストに対して課金される場合があります。

営業状況を確認する

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() の呼び出しに対して、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 で使用されている ID と同じです。1 つのプレイス ID が参照できる場所は 1 つのみですが、1 つの場所に複数のプレイス ID が存在することがあります。他の状況では、プレイスが新しいプレイス ID を取得する原因となる場合があります。たとえば、ビジネスが新しい場所に移転した場合などに発生する可能性があります。

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

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