Nearby Search (Baru)

Pilih platform: Android iOS JavaScript Layanan Web

Permintaan Nearby Search (Baru) menggunakan wilayah untuk penelusuran yang ditetapkan sebagai lingkaran, yang didefinisikan oleh koordinat lintang dan bujur dari titik tengah lingkaran dan radius dalam meter. Permintaan tersebut menampilkan daftar tempat yang cocok, yang masing-masing diwakili oleh objek Place, dalam area penelusuran yang ditentukan.

Secara default, respons akan berisi semua jenis tempat dalam area penelusuran. Secara opsional, Anda dapat memfilter respons dengan menentukan daftar jenis tempat yang secara eksplisit disertakan dalam atau dikecualikan dari respons. Misalnya, Anda dapat menentukan untuk hanya menyertakan tempat tersebut 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 informasi selengkapnya, lihat Memilih versi SDK.

Permintaan Nearby Search (Baru)

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

Objek SearchNearbyRequest menentukan semua parameter yang diperlukan dan opsional untuk permintaan. Parameter yang diperlukan 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.
• Pembatasan lokasi untuk area penelusuran, yang didefinisikan sebagai pasangan garis lintang/bujur dan nilai radius, dalam meter.

Contoh permintaan penelusuran terdekat ini menetapkan bahwa objek Place respons berisi kolom tempat Place.Field.ID dan Place.Field.NAME untuk setiap objek Place dalam hasil penelusuran. Fungsi ini juga memfilter respons agar 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.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();
    });

Anda dapat menggunakan CancellationToken untuk mencoba membatalkan permintaan ke salah satu class permintaan (misalnya, FetchPlaceRequest). Pembatalan dilakukan atas dasar upaya terbaik. Setelah permintaan pembatalan diajukan, tidak ada respons yang akan dikembalikan. Menerbitkan token pembatalan TIDAK menjamin bahwa permintaan tertentu akan dibatalkan, dan Anda mungkin tetap dikenai biaya atas 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 objek Place hanya berisi kolom yang ditentukan oleh daftar kolom yang diteruskan dalam permintaan.

Misalnya, dalam permintaan, Anda menentukan daftar kolom sebagai:

// 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 Tempat.

Parameter wajib

Gunakan objek SearchNearbyRequest untuk menentukan parameter yang diperlukan untuk penelusuran.

• Daftar kolom

  Saat meminta detail tempat, 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 adalah praktik desain yang baik untuk memastikan Anda tidak meminta data yang tidak perlu. Cara ini akan membantu menghindari waktu pemrosesan dan biaya penagihan yang tidak perlu.

  Tentukan satu atau beberapa kolom berikut:

  • Kolom berikut memicu SKU Nearby Search (Basic):

    Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.ID, Place.Field.NAME, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

  • Kolom berikut memicu SKU Nearby Search (Advanced):

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

  • Kolom berikut memicu SKU Nearby Search (Preferred):

    Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

  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.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.NAME);

• Pembatasan lokasi

  Objek LocationRestriction yang menentukan wilayah yang akan ditelusuri dan ditetapkan sebagai lingkaran, yang ditentukan berdasarkan titik tengah dan radius dalam meter. Radius harus antara lebih besar dari 0,0 dan kurang dari atau sama dengan 50.000,0.Perlu diingat bahwa menentukan radius yang terlalu kecil akan menampilkan ZERO_RESULTS sebagai respons.

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

Parameter opsional

Gunakan objek SearchNearbyRequest guna menentukan parameter opsional untuk penelusuran.

• Jenis dan jenis primer

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

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

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

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

  Jika penelusuran ditentukan dengan beberapa pembatasan jenis, hanya tempat yang memenuhi semua pembatasan yang akan ditampilkan. Misalnya, jika Anda menentukan includedTypes = Arrays.asList("restaurant") dan excludedPrimaryTypes = Arrays.asList("steak_house"), tempat yang ditampilkan memberikan 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 pembatasan 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 dihilangkan, semua jenis tempat akan ditampilkan.

  Untuk menetapkan parameter jenis yang disertakan, panggil metode setIncludedTypes() saat membuat 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, maka respons akan menyertakan tempat yang dikategorikan sebagai "school", tetapi bukan sebagai "primary_school". Respons mencakup tempat yang cocok dengan setidaknya salah satu dari includedTypes dan tidak satu pun dari 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 membuat 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 membuat 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 membuat objek SearchNearbyRequest.

• Jumlah hasil maksimum

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

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

• Preferensi peringkat

  Jenis peringkat yang akan digunakan. Jika parameter ini dihilangkan, hasil akan diurutkan berdasarkan popularitas. Mungkin 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 membuat objek SearchNearbyRequest.

• Kode wilayah

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

  Jika nama negara kolom formattedAddress dalam respons cocok dengan regionCode, kode negara akan dihilangkan dari formattedAddress.

  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.

  Untuk menetapkan parameter kode wilayah, panggil metode setRegionCode() saat membuat 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.