Nearby Search (Baru)

Pilih platform: Android iOS JavaScript Web Service

Developer Wilayah Ekonomi Eropa (EEA)

Jika alamat penagihan Anda berada di Wilayah Ekonomi Eropa, mulai 8 Juli 2025, Persyaratan Layanan Google Maps Platform EEA akan berlaku untuk penggunaan Layanan oleh Anda. Fungsi bervariasi menurut wilayah. Pelajari lebih lanjut.

Permintaan Nearby Search (Baru) menggunakan wilayah yang akan ditelusuri sebagai input yang ditentukan sebagai lingkaran, yang ditentukan oleh koordinat lintang dan bujur titik pusat lingkaran dan radius dalam meter. Permintaan ini menampilkan daftar tempat yang cocok, yang masing-masing diwakili oleh Place objek, dalam area penelusuran yang ditentukan.

Secara default, respons berisi tempat dari semua jenis dalam area penelusuran. Anda dapat secara opsional memfilter respons dengan menentukan daftar jenis tempat yang akan disertakan atau dikecualikan secara eksplisit dari respons. Misalnya, Anda dapat menentukan untuk hanya menyertakan tempat dalam respons yang berjenis "restaurant", "bakery", dan "cafe", atau mengecualikan semua tempat berjenis "school".

Catatan: Nearby Search (Baru) tersedia di Places SDK for Android versi 3.5.0 dan yang lebih baru. Untuk mengetahui informasi selengkapnya, lihat Memilih versi SDK. Untuk mengetahui informasi selengkapnya tentang penggunaan Places API Kotlin yang ditambahkan di versi 4.0.0, lihat Ringkasan Referensi.

Permintaan Nearby Search (Baru)

Buat permintaan Nearby Search (Baru) dengan memanggil PlacesClient.searchNearby, yang meneruskan objek SearchNearbyRequest yang menentukan parameter permintaan.

Objek SearchNearbyRequest menentukan semua parameter wajib dan opsional untuk permintaan. Parameter wajib mencakup:

• Daftar kolom yang akan ditampilkan dalam objek Place, yang juga dikenal sebagai mask kolom. Jika Anda tidak menentukan setidaknya satu kolom dalam daftar kolom, atau jika Anda menghapus daftar kolom, panggilan akan menampilkan error.
• Batasan lokasi untuk area penelusuran, yang ditentukan sebagai pasangan lintang/bujur dan nilai radius, dalam meter.

Contoh permintaan Nearby Search ini menentukan bahwa objek Place respons berisi kolom tempat Place.Field.ID dan Place.Field.DISPLAY_NAME untuk setiap objek Place dalam hasil penelusuran. Respons juga difilter untuk hanya menampilkan tempat berjenis "restaurant" dan "cafe", tetapi mengecualikan tempat berjenis "pizza_restaurant" dan "american_restaurant".

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

Catatan: Untuk mengetahui informasi selengkapnya tentang cara menginisialisasi PlacesClient, lihat Menginisialisasi klien Places API.

Anda dapat menggunakan CancellationToken untuk mencoba membatalkan permintaan ke salah satu class permintaan (misalnya, FetchPlaceRequest). Pembatalan dilakukan dengan upaya terbaik. Setelah permintaan pembatalan dikeluarkan, tidak ada respons yang akan ditampilkan. Mengeluarkan token pembatalan TIDAK menjamin bahwa permintaan tertentu akan dibatalkan, dan Anda mungkin masih akan ditagih untuk permintaan tersebut meskipun tidak ada respons yang ditampilkan.

Respons Nearby Search (Baru)

Class SearchNearbyResponse mewakili respons dari permintaan penelusuran. Objek SearchNearbyResponse berisi:

• Daftar objek Place yang mewakili semua tempat yang cocok, dengan satu objek Place per tempat yang cocok.
• Setiap Place objek hanya berisi kolom yang ditentukan oleh daftar kolom diteruskan dalam permintaan.

Misalnya, dalam permintaan, Anda menentukan daftar kolom sebagai berikut:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

Daftar kolom ini berarti bahwa setiap objek Place dalam respons hanya berisi ID tempat dan nama setiap tempat yang cocok. Anda kemudian dapat menggunakan metode Place.getId() dan Place.getName() untuk mengakses kolom ini di setiap objek Place.

Untuk contoh lainnya tentang cara mengakses data dalam objek Place, lihat Mengakses kolom data objek Place.

Parameter yang diperlukan

Gunakan SearchNearbyRequest objek untuk menentukan parameter yang diperlukan untuk penelusuran.

• Daftar kolom

  Saat meminta Place Details, Anda harus menentukan data yang akan ditampilkan dalam objek Place untuk tempat tersebut sebagai mask kolom. Untuk menentukan mask kolom, teruskan array nilai dari Place.Field ke objek SearchNearbyRequest. Penyamaran kolom merupakan praktik desain yang baik untuk memastikan Anda tidak meminta data yang tidak diperlukan. Cara ini akan membantu Anda menghindari waktu pemrosesan dan biaya penagihan yang tidak perlu.

  Tentukan satu atau beberapa kolom berikut:

  • Kolom berikut memicu Nearby Search Pro SKU:

    Place.Field.ADDRESS_COMPONENTS
Place.Field.BUSINESS_STATUS
Place.Field.ADDRESS
Place.Field.DISPLAY_NAME >*
        * Gunakan sebagai pengganti Place.Field.NAME, yang tidak digunakan lagi.
    Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL*
        * Gunakan sebagai pengganti Place.Field.ICON_URL, yang tidak digunakan lagi.
    Place.Field.ID
Place.Field.LAT_LNG
Place.Field.PHOTO_METADATAS
Place.Field.PLUS_CODE
Place.Field.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.RESOURCE_NAME
Place.Field.TYPES
Place.Field.UTC_OFFSET
Place.Field.VIEWPORT
Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    Untuk daftar lengkap kolom dan SKU terkait, lihat Kolom Data Tempat (Baru).

  • Kolom berikut memicu Nearby Search Enterprise SKU:

    Place.Field.CURRENT_OPENING_HOURS
Place.Field.CURRENT_SECONDARY_OPENING_HOURS
Place.Field.INTERNATIONAL_PHONE_NUMBER*
        * Gunakan sebagai pengganti Place.Field.PHONE_NUMBER, yang tidak digunakan lagi.
    Place.Field.NATIONAL_PHONE_NUMBER
Place.Field.OPENING_HOURS
Place.Field.PRICE_LEVEL
Place.Field.RATING
Place.Field.SECONDARY_OPENING_HOURS
Place.Field.USER_RATING_COUNT*
        * Gunakan sebagai pengganti Place.Field.USER_RATINGS_TOTAL, yang tidak digunakan lagi.
    Place.Field.WEBSITE_URI

    Untuk daftar lengkap kolom dan SKU terkait, lihat Kolom Data Tempat (Baru).

  • Kolom berikut memicu Nearby Search Enterprise Plus SKU:

    Place.Field.ALLOWS_DOGS
Place.Field.CURBSIDE_PICKUP
Place.Field.DELIVERY
Place.Field.DINE_IN
Place.Field.EDITORIAL_SUMMARY
Place.Field.EV_CHARGE_OPTIONS
Place.Field.FUEL_OPTIONS
Place.Field.GOOD_FOR_CHILDREN
Place.Field.GOOD_FOR_GROUPS
Place.Field.GOOD_FOR_WATCHING_SPORTS
Place.Field.LIVE_MUSIC
Place.Field.MENU_FOR_CHILDREN
Place.Field.OUTDOOR_SEATING
Place.Field.PARKING_OPTIONS
Place.Field.PAYMENT_OPTIONS
Place.Field.RESERVABLE
Place.Field.RESTROOM
Place.Field.REVIEWS
Place.Field.SERVES_BEER
Place.Field.SERVES_BREAKFAST
Place.Field.SERVES_BRUNCH
Place.Field.SERVES_COCKTAILS
Place.Field.SERVES_COFFEE
Place.Field.SERVES_DESSERT
Place.Field.SERVES_DINNER
Place.Field.SERVES_LUNCH
Place.Field.SERVES_VEGETARIAN_FOOD
Place.Field.SERVES_WINE
Place.Field.TAKEOUT

    Untuk daftar lengkap kolom dan SKU terkait, lihat Kolom Data Tempat (Baru).

  Untuk menetapkan parameter daftar kolom, panggil metode setPlaceFields() saat mem-build objek SearchNearbyRequest.

  Contoh berikut menentukan daftar dua nilai kolom untuk menentukan bahwa objek Place yang ditampilkan oleh permintaan berisi kolom Place.Field.ID dan Place.Field.DISPLAY_NAME:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

• Batasan lokasi

  Objek LocationRestriction yang menentukan wilayah yang akan ditelusuri yang ditentukan sebagai lingkaran, yang ditentukan oleh titik pusat dan radius dalam meter. Radius harus antara lebih besar dari 0,0 dan kurang dari atau sama dengan 50000,0, dengan mengingat bahwa menentukan radius yang terlalu kecil akan menampilkan ZERO_RESULTS sebagai respons.

  Untuk menetapkan parameter batasan lokasi, panggil metode setLocationRestriction() saat mem-build objek SearchNearbyRequest.

Parameter opsional

Gunakan objek SearchNearbyRequest untuk menentukan parameter opsional untuk penelusuran.

• Jenis dan jenis utama

  Memungkinkan Anda menentukan daftar jenis dari jenis Tabel A yang digunakan untuk memfilter hasil penelusuran. Maksimal 50 jenis dapat ditentukan di setiap kategori batasan jenis.

  Catatan: Nilai dalam Tabel B hanya ditampilkan dalam respons. Anda tidak dapat menggunakan nilai dalam Tabel B sebagai filter.

  Tempat hanya dapat memiliki satu jenis utama dari jenis Tabel A yang terkait dengan itu. Misalnya, jenis utama mungkin "mexican_restaurant" atau "steak_house". Gunakan includedPrimaryTypes dan excludedPrimaryTypes untuk memfilter hasil berdasarkan jenis utama tempat.

  Tempat juga dapat memiliki beberapa nilai jenis dari jenis Tabel A yang terkait dengannya. Misalnya, restoran mungkin memiliki jenis berikut: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Gunakan includedTypes dan excludedTypes untuk memfilter hasil berdasarkan daftar jenis yang terkait dengan tempat.

  Saat Anda menentukan jenis utama umum, seperti "restaurant" atau "hotel", respons dapat berisi tempat dengan jenis utama yang lebih spesifik daripada yang ditentukan. Misalnya, Anda menentukan untuk menyertakan jenis utama "restaurant". Respons kemudian dapat berisi tempat dengan jenis utama "restaurant", tetapi respons juga dapat berisi tempat dengan jenis utama yang lebih spesifik, seperti "chinese_restaurant" atau "seafood_restaurant".

  Jika penelusuran ditentukan dengan beberapa batasan jenis, hanya tempat yang memenuhi semua batasan yang akan ditampilkan. Misalnya, jika Anda menentukan includedTypes = Arrays.asList("restaurant") dan excludedPrimaryTypes = Arrays.asList("steak_house"), tempat yang ditampilkan akan menyediakan layanan terkait "restaurant" tetapi tidak beroperasi terutama sebagai "steak_house".

  Jika Anda menghapus includedTypes, excludedTypes, includedPrimaryTypes, dan excludedPrimaryTypes dari permintaan, penelusuran akan menampilkan tempat untuk semua jenis dari dalam batas batasan lokasi.

  Untuk contoh cara menggunakan includedTypes dan excludedTypes, lihat Permintaan Nearby Search (Baru).

  Jenis yang disertakan

  Daftar jenis tempat dari Tabel A yang akan ditelusuri. Jika parameter ini dihapus, tempat dari semua jenis akan ditampilkan.

  Untuk menetapkan parameter jenis yang disertakan, panggil metode setIncludedTypes() saat mem-build objek SearchNearbyRequest.

  Jenis yang dikecualikan

  Daftar jenis tempat dari Tabel A yang akan dikecualikan dari penelusuran.

  Jika Anda menentukan includedTypes (seperti "school") dan excludedTypes (seperti "primary_school") dalam permintaan, respons akan menyertakan tempat yang dikategorikan sebagai "school" tetapi tidak sebagai "primary_school". Respons menyertakan tempat yang cocok dengan setidaknya satu dari includedTypes dan tidak ada excludedTypes.

  Jika ada jenis yang bertentangan, seperti jenis yang muncul di includedTypes dan excludedTypes, error INVALID_REQUEST akan ditampilkan.

  Untuk menetapkan parameter jenis yang dikecualikan, panggil metode setExcludedTypes() saat mem-build objek SearchNearbyRequest.

  Jenis utama yang disertakan

  Daftar jenis tempat utama dari Tabel A yang akan disertakan dalam penelusuran.

  Untuk menetapkan parameter jenis utama yang disertakan, panggil metode setIncludedPrimaryTypes() saat mem-build objek SearchNearbyRequest.

  Jenis utama yang dikecualikan

  Daftar jenis tempat utama dari Tabel A yang akan dikecualikan dari penelusuran.

  Jika ada jenis utama yang bertentangan, seperti jenis yang muncul di includedPrimaryTypes dan excludedPrimaryTypes, error INVALID_ARGUMENT akan ditampilkan.

  Untuk menetapkan parameter jenis utama yang dikecualikan, panggil metode setExcludedPrimaryTypes() saat mem-build objek SearchNearbyRequest.

• Jumlah hasil maksimum

  Menentukan jumlah maksimum hasil tempat yang akan ditampilkan. Harus antara 1 dan 20 (default) inklusif.

  Untuk menetapkan parameter jumlah hasil maksimum, panggil metode setMaxResultCount() saat mem-build objek SearchNearbyRequest.

• Preferensi peringkat

  Jenis peringkat yang akan digunakan. Jika parameter ini dihapus, hasil akan diurutkan berdasarkan popularitas. Dapat berupa salah satu dari hal berikut:

  • POPULARITY (default) Mengurutkan hasil berdasarkan popularitasnya.
  • DISTANCE Mengurutkan hasil dalam urutan menaik berdasarkan jaraknya dari lokasi yang ditentukan.

  Untuk menetapkan parameter preferensi peringkat, panggil metode setRankPreference() saat mem-build objek SearchNearbyRequest.

• Kode wilayah

  Kode wilayah yang digunakan untuk memformat respons, yang ditentukan sebagai nilai kode CLDR dua karakter. Tidak ada nilai default.

  Jika nama negara kolom FORMATTED_ADDRESS dalam respons cocok dengan regionCode, kode negara akan dihapus dari FORMATTED_ADDRESS.

  Sebagian besar kode CLDR identik dengan ISO 3166-1 codes, dengan beberapa pengecualian. Misalnya, ccTLD Inggris Raya adalah "uk" (.co.uk), sedangkan kode ISO 3166-1-nya adalah "gb" (secara teknis untuk entitas "The United Kingdom of Great Britain and Northern Ireland"). Parameter ini dapat memengaruhi hasil berdasarkan hukum yang berlaku.

  Untuk menetapkan parameter kode wilayah, panggil metode setRegionCode() saat mem-build objek SearchNearbyRequest.

Menampilkan atribusi dalam aplikasi Anda

Saat aplikasi Anda menampilkan informasi yang diperoleh dari PlacesClient, seperti foto dan ulasan, aplikasi juga harus menampilkan atribusi yang diperlukan.

Untuk mengetahui informasi selengkapnya, lihat Kebijakan untuk Places SDK for Android.