Place Details

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

Places SDK for Android は、場所の名前と住所、緯度と経度の座標で指定された地理的位置、場所の種類(ナイトクラブ、ペットショップ、博物館など)など、場所に関する豊富な情報をアプリに提供します。特定の場所のこうした情報にアクセスするには、場所を一意に識別する不変の ID であるプレイス 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 オブジェクトにない場合、関連するメソッドは null を返します。以下に、使用可能なメソッドのいくつかの例を示します。すべてのメソッドの一覧については、Place API リファレンスをご覧ください。

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

    Place オブジェクトには、今後 7 日間の場所の営業時間を返す getCurrentOpeningHours() メソッドと、今後 7 日間の場所のサブの営業時間を返す getSecondaryOpeningHours() メソッドも含まれています。

  • isOpen() - 場所が現在営業しているかどうかを示すブール値。時間を指定しない場合、デフォルトは現在です。isOpen は、Place.Field.UTC_OFFSETPlace.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 に新しいデータが追加されています。

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

このデータにアクセスするには、Places SDK for Android(新規)を有効にする必要があります。2 つの SDK バージョンの主な違いについては、SDK バージョンを選択するをご覧ください。

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

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

それぞれの場所には、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(新規): バージョン 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 オブジェクトにレビューを入力するには、次のことを行う必要があります。

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

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

既存の 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 は TaskFetchPlaceResponse を返します。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 を指定する文字列。
  • 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 をご覧ください。

次の例は、場所が現在営業しているかどうかを判別します。この例では、プレイス 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 が含まれる場合があります。

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