Places SDK for Android memberikan aplikasi Anda informasi lengkap tentang berbagai tempat, termasuk nama dan alamat tempat, lokasi geografis yang ditentukan sebagai koordinat lintang/bujur, jenis tempat (seperti klub malam, toko hewan peliharaan, museum), dan lainnya. Untuk mengakses informasi ini bagi tempat tertentu, Anda dapat menggunakan ID tempat, ID stabil yang mengidentifikasi tempat secara unik.
Detail tempat
Objek
Place
memberikan informasi tentang tempat tertentu. Anda bisa mendapatkan objek Place
dengan cara berikut:
- Panggil
PlacesClient.findCurrentPlace()
– Lihat panduan untuk mendapatkan tempat saat ini. - Panggil
PlacesClient.fetchPlace()
– Lihat panduan untuk mendapatkan tempat berdasarkan ID.
Saat meminta tempat, Anda harus menentukan data tempat mana yang akan ditampilkan. Untuk melakukannya, teruskan daftar nilai Place.Field yang menentukan data yang akan ditampilkan. Daftar ini merupakan pertimbangan penting karena memengaruhi biaya untuk setiap permintaan.
Karena hasil data tempat tidak boleh kosong, hanya hasil tempat dengan data yang dikembalikan (misalnya, jika tempat yang diminta tidak memiliki foto, kolom photos
tidak akan ada dalam hasil).
Contoh berikut meneruskan daftar tiga nilai Place.Field untuk menentukan data yang ditampilkan oleh permintaan:
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)
Setelah mendapatkan objek Place
, gunakan metode objek untuk mengakses
kolom data yang ditentukan dalam permintaan. Jika kolom ini tidak ada di objek Place
,
metode terkait akan menampilkan null. Berikut ini adalah contoh beberapa metode yang tersedia.
Untuk mengetahui daftar lengkap semua metode, lihat referensi API
Place
.
getAddress()
– Alamat tempat, dalam format yang dapat dibaca manusia.getAddressComponents()
–List
komponen alamat untuk tempat ini. Komponen ini disediakan untuk mengekstrak informasi terstruktur tentang alamat suatu tempat, misalnya menemukan kota tempat suatu tempat berada. Jangan gunakan komponen ini untuk pemformatan alamat; sebagai gantinya, panggilgetAddress()
, yang menyediakan alamat berformat yang dilokalkan.getId()
– ID tekstual untuk tempat. Baca selengkapnya tentang ID tempat di sisa halaman ini.getLatLng()
– Lokasi geografis suatu tempat, yang ditetapkan sebagai koordinat lintang dan bujur.getName()
– Nama tempat.getOpeningHours()
–OpeningHours
tempat. PanggilOpeningHours.getWeekdayText()
untuk menampilkan daftar string yang mewakili jam buka dan tutup untuk setiap hari. PanggilOpeningHours.getPeriods()
untuk menampilkan daftar objekperiod
dengan informasi lebih mendetail yang setara dengan data yang disediakan olehgetWeekdayText()
.Objek
Place
juga berisi metodegetCurrentOpeningHours()
yang menampilkan jam operasional suatu tempat selama tujuh hari ke depan dangetSecondaryOpeningHours()
yang menampilkan jam operasional sekunder suatu tempat selama tujuh hari ke depan.isOpen()
– Boolean yang menunjukkan apakah tempat tersebut sedang buka. Jika tidak ada waktu yang ditentukan, defaultnya adalah sekarang.isOpen
hanya akan ditampilkan jikaPlace.Field.UTC_OFFSET
danPlace.Field.OPENING_HOURS
tersedia. Untuk memastikan hasil yang akurat, minta kolomPlace.Field.BUSINESS_STATUS
danPlace.Field.UTC_OFFSET
dalam permintaan tempat Anda yang asli. Jika tidak diminta, diasumsikan bahwa bisnis tersebut beroperasi. Tonton video ini untuk mengetahui cara menggunakanisOpen
dengan Place Details.
Beberapa contoh sederhana:
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
Mendapatkan tempat melalui ID
ID tempat adalah ID tekstual yang secara unik mengidentifikasi tempat. Di
Places SDK for Android, Anda dapat mengambil ID tempat dengan memanggil
Place.getId()
.
Layanan Place Autocomplete juga menampilkan ID tempat untuk setiap tempat yang cocok dengan filter dan kueri penelusuran yang diberikan. Anda juga bisa menyimpan ID tempat dan menggunakannya untuk mengambil objek Place
lagi nanti.
Untuk mendapatkan tempat berdasarkan ID, panggil
PlacesClient.fetchPlace()
,
dengan meneruskan FetchPlaceRequest
.
API menampilkan
FetchPlaceResponse
dalam
Task
.
FetchPlaceResponse
berisi
objek Place
yang cocok dengan ID tempat yang diberikan.
Contoh kode berikut menunjukkan cara memanggil fetchPlace()
untuk
mendapatkan detail tempat yang ditentukan.
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") } }
Mendapatkan status terbuka
Metode PlacesClient.isOpen(IsOpenRequest request)
menampilkan objek IsOpenResponse
yang menunjukkan apakah tempat tersebut
saat ini buka berdasarkan waktu yang ditentukan dalam panggilan.
Metode ini mengambil satu argumen dari jenis IsOpenRequest
yang berisi:
- Objek
Place
, atau string yang menentukan ID tempat. - Nilai waktu opsional yang menentukan waktu dalam milidetik dari 1970-01-01T00:00:00Z. Jika tidak ada waktu yang ditentukan, defaultnya adalah sekarang.
Metode ini mengharuskan kolom berikut ada di objek Place
:
Place.Field.BUSINESS_STATUS
Place.Field.CURRENT_OPENING_HOURS
Place.Field.OPENING_HOURS
Place.Field.UTC_OFFSET
Jika kolom ini tidak disediakan di objek Place
, atau jika Anda meneruskan ID tempat, metode ini akan menggunakan PlacesClient.fetchPlace()
untuk mengambilnya. Untuk informasi selengkapnya tentang cara membuat objek Tempat dengan kolom yang diperlukan,
lihat Detail tempat.
Contoh berikut menentukan apakah tempat saat ini buka. Dalam contoh ini, Anda hanya meneruskan
ID tempat ke 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()); // ...
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 } // ...
Contoh berikutnya menunjukkan pemanggilan isOpen()
tempat Anda meneruskan objek Place
.
Objek Place
harus berisi ID tempat yang valid:
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()); // ... }); // ...
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 } // ... } // ...
Menampilkan atribusi dalam aplikasi Anda
Jika aplikasi Anda menampilkan informasi tempat, aplikasi tersebut juga harus menampilkan atribusi. Lihat dokumentasi tentang atribusi.
Selengkapnya tentang ID tempat
ID tempat yang digunakan di Places SDK for Android adalah ID yang sama dengan yang digunakan di Places API. Setiap ID tempat hanya bisa merujuk ke satu tempat, tetapi satu tempat bisa memiliki lebih dari satu ID tempat. Ada keadaan lain yang dapat menyebabkan tempat mendapatkan ID tempat baru. Misalnya, hal ini dapat terjadi jika bisnis pindah ke lokasi baru.
Saat meminta tempat dengan menetapkan ID tempat, Anda bisa yakin bahwa Anda akan selalu menerima tempat yang sama dalam respons (jika tempat tersebut masih ada). Akan tetapi, perhatikan bahwa respons itu mungkin berisi ID tempat yang berbeda dari yang diminta dalam permintaan Anda.
Untuk informasi selengkapnya, lihat ringkasan ID tempat.