Places SDK for Android memberi aplikasi Anda informasi yang lengkap tentang tempat, termasuk nama dan alamat tempat, lokasi geografis yang ditetapkan sebagai koordinat lintang/bujur, jenis tempat (seperti klub malam, toko hewan peliharaan, museum), dan lainnya. Untuk mengakses informasi ini untuk tempat tertentu, Anda dapat menggunakan ID tempat, yaitu ID stabil yang secara unik mengidentifikasi tempat.
Detail tempat
Objek
Place
memberikan informasi tentang tempat tertentu. Anda dapat memperoleh objek Place
dengan cara berikut:
- Panggil
PlacesClient.fetchPlace()
– Lihat panduan untuk mendapatkan tempat berdasarkan ID. - Panggil
PlacesClient.findCurrentPlace()
– Lihat panduan untuk mendapatkan lokasi saat ini.
Saat meminta tempat, Anda harus menentukan data tempat yang akan dikembalikan. 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 ditampilkan (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:
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 ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Mengakses kolom data objek Tempat
Setelah mendapatkan objek Place
, gunakan metode objek untuk mengakses kolom data yang ditentukan dalam permintaan. Jika kolom tidak ada di objek Place
,
metode terkait akan menampilkan null. Berikut adalah contoh dari 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 tujuan mengekstrak informasi terstruktur tentang alamat suatu tempat, misalnya menemukan kota di mana suatu tempat berada. Jangan gunakan komponen ini untuk pemformatan alamat; sebagai gantinya, panggilgetAddress()
, yang memberikan alamat berformat yang sudah dilokalkan.getId()
– ID tekstual untuk tempat tersebut. Baca selengkapnya tentang ID tempat di bagian lainnya halaman ini.getLatLng()
– Lokasi geografis tempat, 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 dalam seminggu. PanggilOpeningHours.getPeriods()
untuk menampilkan daftar objekperiod
dengan informasi lebih mendetail yang setara dengan data yang diberikan olehgetWeekdayText()
.Objek
Place
juga berisi metodegetCurrentOpeningHours()
yang menampilkan jam buka suatu tempat selama tujuh hari ke depan, dangetSecondaryOpeningHours()
yang menampilkan jam buka sekunder suatu tempat selama tujuh hari ke depan.isOpen()
– Boolean yang menunjukkan apakah tempat saat ini buka. Jika tidak ada waktu yang ditentukan, waktu 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 asli Anda. Jika tidak diminta, dianggap bahwa bisnis masih beroperasi. Tonton video ini untuk mengetahui cara menggunakanisOpen
dengan Place Details.
Beberapa contoh sederhana:
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();
Mengakses data Tempat yang ditambahkan di versi 3.3.0
Places SDK for Android versi 3.3.0 menambahkan data baru ke
Place
:
- Jenis tempat: Nilai jenis baru yang terkait dengan tempat.
- Ulasan: Maksimal lima ulasan untuk suatu tempat.
- Kode bahasa nama: Kode bahasa untuk nama tempat.
Bagian berikut menjelaskan cara mengakses data baru ini.
Mengakses jenis tempat baru
Setiap tempat dapat memiliki satu atau beberapa nilai type yang terkait dengannya. Places SDK for Android versi 3.3.0 menambahkan banyak nilai jenis baru. Untuk daftar lengkapnya, lihat Jenis tempat yang diperluas.
Pada Places SDK for Android versi 3.2.0 dan versi sebelumnya, Anda menggunakan metode Place.getTypes()
untuk mengakses nilai jenis yang terkait dengan tempat. Place.getTypes()
menampilkan
daftar jenis sebagai nilai enum yang ditentukan oleh
Place.Types
.
Metode Place.getPlaceTypes()
menampilkan nilai jenis sebagai daftar nilai string. Nilai yang ditampilkan bergantung pada versi Places SDK for Android Anda:
- Places SDK for Android (Baru): Menampilkan string yang ditentukan oleh Tabel A dan Tabel B yang ditampilkan di Jenis Tempat (Baru), termasuk semua jenis tempat yang ditambahkan di versi 3.3.0.
- Places SDK for Android: Menampilkan enum yang ditentukan oleh
Place.Types
, yang tidak menyertakan jenis baru yang ditambahkan pada versi 3.3.0.
Untuk mempelajari perbedaan utama antara kedua versi SDK, lihat Memilih versi SDK.
Mengakses ulasan tempat
Places SDK for Android (Baru) menambahkan class Review
, yang berisi ulasan suatu tempat. Objek Place
dapat berisi hingga lima ulasan.
Class Review
juga dapat berisi atribusi dan atribusi penulis. Jika menampilkan ulasan di aplikasi, Anda juga harus menampilkan atribusi atau atribusi penulis.
Untuk informasi selengkapnya, lihat Menampilkan ulasan.
Untuk mengisi objek Place
dengan ulasan, Anda harus:
- Aktifkan SDK baru saat Anda Menyiapkan project Google Cloud.
- Lakukan inisialisasi SDK baru dalam aktivitas atau fragmen.
- Menyertakan
Place.Field.REVIEWS
dalam daftar kolom permintaan detail tempat. - Panggil
PlacesClient.fetchPlace()
. Kolom ulasan tidak didukung olehPlacesClient.findCurrentPlace()
. - Gunakan metode
Place.getReviews()
untuk mengakses kolom data ulasan di objekPlace
.
Mengakses kode bahasa nama tempat
Metode Place.getName()
yang ada
menampilkan string teks yang berisi nama tempat. Untuk mengisi objek Place
dengan nama tempat, Anda harus menyertakan Place.Field.NAME
dalam daftar kolom
permintaan detail tempat.
Objek Place
kini berisi kode bahasa untuk string nama. Untuk
mengisi objek Place
dengan kode bahasa, Anda harus:
- Aktifkan SDK baru saat Anda Menyiapkan project Google Cloud.
- Lakukan inisialisasi SDK baru dalam aktivitas atau fragmen.
- Sertakan
Place.Field.NAME
dalam daftar kolom permintaan. Nilai ini mengonfigurasi respons untuk menyertakan nama tempat dan kode bahasa di objekPlace
. - Panggil
PlacesClient.fetchPlace()
.PlacesClient.findCurrentPlace()
tidak mendukung kolom kode bahasa. - Gunakan metode
Place.getNameLanguageCode()
untuk mengakses kolom kode bahasa di objekPlace
.
Setel kode wilayah di versi 3.3.0
Places SDK for Android (Baru) menambahkan parameter permintaan kode wilayah ke Place Details. Kode wilayah digunakan untuk memformat respons, yang ditetapkan sebagai nilai kode CLDR dua karakter. Parameter ini juga dapat memiliki efek bias pada hasil penelusuran. Tidak ada nilai default. Anda harus mengaktifkan SDK baru untuk menetapkan kode wilayah.
Jika nama negara pada kolom alamat dalam respons cocok dengan kode wilayah, kode negara akan dihapus dari alamat.
Sebagian besar kode CLDR identik dengan kode ISO 3166-1, dengan beberapa pengecualian. Misalnya, ccTLD Inggris Raya adalah "uk" (.co.uk) sedangkan kode ISO 3166-1-nya adalah "gb" (secara teknis untuk entitas "Inggris Raya dan Irlandia Utara"). Parameter ini dapat memengaruhi hasil berdasarkan hukum yang berlaku.
Mendapatkan tempat melalui ID
ID tempat adalah ID tekstual yang secara unik mengidentifikasi tempat. Di Places SDK for Android, Anda dapat mengambil ID suatu tempat dengan memanggil Place.getId()
.
Layanan Place Autocomplete juga menampilkan ID tempat untuk setiap tempat yang cocok dengan kueri penelusuran dan filter yang diberikan. Anda dapat 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 pemanggilan fetchPlace()
untuk mendapatkan detail tempat yang ditentukan.
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. } });
Mendapatkan status buka
Metode PlacesClient.isOpen(IsOpenRequest request)
menampilkan objek IsOpenResponse
yang menunjukkan apakah tempat ini
saat ini buka berdasarkan waktu yang ditentukan dalam panggilan.
Metode ini menggunakan 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, waktu defaultnya adalah sekarang.
Metode ini memerlukan 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 dalam objek Place
, atau jika Anda meneruskan ID tempat,
metode tersebut akan menggunakan
PlacesClient.fetchPlace()
untuk mengambilnya. Untuk informasi selengkapnya tentang cara membuat objek Tempat dengan kolom yang diperlukan,
lihat Place Details.
Contoh berikut menentukan apakah tempat saat ini buka. Dalam contoh ini, Anda hanya meneruskan ID tempat ke 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()); // ...
Contoh berikutnya menunjukkan pemanggilan isOpen()
tempat Anda meneruskan objek Place
.
Objek Place
harus berisi ID tempat yang valid:
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()); // ... }); // ...
Menampilkan atribusi dalam aplikasi Anda
Saat aplikasi Anda menampilkan informasi tempat, termasuk ulasan tempat, aplikasi juga harus menampilkan atribusi apa pun. Untuk informasi selengkapnya, lihat atribusi.
Selengkapnya tentang ID tempat
ID tempat yang digunakan di Places SDK for Android adalah ID yang sama seperti 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 suatu tempat mendapatkan ID tempat baru. Misalnya, hal ini dapat terjadi jika bisnis pindah ke lokasi baru.
Saat Anda meminta tempat dengan menentukan ID tempat, Anda bisa yakin bahwa Anda akan selalu menerima tempat yang sama dalam respons (jika tempat itu masih ada). Namun, perhatikan bahwa respons tersebut mungkin berisi ID tempat yang berbeda dari yang ada dalam permintaan Anda.
Untuk informasi selengkapnya, lihat ringkasan ID tempat.