Places SDK for Android は、場所の名前や住所、緯度と経度の座標で指定された地理的位置、場所のタイプ(ナイトクラブ、ペットショップ、博物館など)など、場所に関する豊富な情報を提供します。特定の場所についてこの情報にアクセスするには、場所 ID を使用できます。場所 ID は、場所を一意に識別する固定 ID です。
場所の詳細
Place
オブジェクトは、特定の場所に関する情報を提供します。Place
オブジェクトは、次の方法で取得できます。
PlacesClient.findCurrentPlace()
を呼び出します。現在の場所を取得する方法についてのガイドをご覧ください。PlacesClient.fetchPlace()
を呼び出します。ID で場所を取得する方法についてのガイドをご覧ください。
場所をリクエストする際は、返す場所データを指定する必要があります。これを行うには、返されるデータを指定する Place.Field 値のリストを渡します。このリストは各リクエストの費用に影響するため、重要な考慮事項です。
プレイスデータの結果は空にできないため、データを含むプレイスの結果のみが返されます(たとえば、リクエストされたプレイスに写真がない場合、結果に photos
フィールドは含まれません)。
次の例では、リクエストによって返されるデータを指定するために 3 つの Place.Field 値のリストを渡します。
Java
// Specify the fields to return. final ListplaceFields = 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)
Place
オブジェクトを取得したら、オブジェクトのメソッドを使用してプレイスデータを取得します。以下に、使用可能なメソッドの一部を示します。すべてのメソッドの一覧については、Place
API リファレンスをご覧ください。
getAddress()
- 人が読める形式の場所の住所。getAddressComponents()
- この場所の住所コンポーネントのList
。これらのコンポーネントは、場所の住所の構造化された情報を抽出する(たとえば、場所がある都市を探す)目的で提供されます。住所の書式設定にこれらのコンポーネントを使用しないでください。代わりに、ローカライズされた住所を提供するgetAddress()
を呼び出してください。getID()
- 場所のテキスト表記の ID です。場所 ID について詳しくは、このページの後半をご覧ください。getLatLng()
- 緯度と経度の座標で指定される場所の地理的位置。getName()
- 場所の名前。getOpeningHours()
- 場所のOpeningHours
。OpeningHours.getWeekdayText()
を呼び出すと、曜日の開始時刻と終了時刻を表す文字列のリストが返されます。OpeningHours.getPeriods()
を呼び出して、period
オブジェクトのリストと、getWeekdayText()
が提供するデータと同じ詳細情報を返します。注: 常に営業している場所は、日曜日の深夜 0 時、closeEvent
は null で表されます。isOpen()
- 店舗が現在営業中かどうかを示すブール値。時間が指定されていない場合、デフォルトは現在です。isOpen
は、Place.Field.UTC_OFFSET
とPlace.Field.OPENING_HOURS
の両方が利用できる場合にのみ返されます。正確な結果を得るには、元の場所リクエストのPlace.Field.BUSINESS_STATUS
フィールドとPlace.Field.UTC_OFFSET
フィールドをリクエストします。リクエストがない場合、ビジネスは運営していると見なされます。isOpen
と Place Details を併用する方法については、こちらの動画をご覧ください。
簡単な例:
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 では、Place.getId()
を呼び出して場所の ID を取得できます。
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") } }
アプリに属性を表示する
アプリで場所情報を表示する場合は、アトリビューションも表示する必要があります。アトリビューションに関するドキュメントをご覧ください。
プレイス ID について
Places SDK for Android で使用される場所 ID は、Places API で使用される ID と同じです。各場所 ID は 1 つの場所のみを参照できますが、1 つの場所には複数の場所 ID を含めることができます。場所が新しいプレイス ID を取得する原因となる状況は他にもあります。これは、ビジネスが新しい場所に移転した場合などに発生します。
場所 ID を指定して場所をリクエストすると、(その場所がまだ存在する場合)常に同じ場所を受け取ることが保証されます。ただし、レスポンスに、リクエストと異なるプレイス ID が含まれていることがあります。
詳しくは、場所 ID の概要をご覧ください。