Text Search (Baru)

Pilih platform: Android iOS JavaScript Layanan Web

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.

Text Search (Baru) menampilkan informasi tentang serangkaian tempat berdasarkan suatu string — misalnya "pizza di Bandung" atau "toko sepatu di dekat Solo" atau "Jl. Rajawali 3". Layanan ini merespons dengan daftar tempat yang cocok dengan string teks dan bias lokasi yang telah ditetapkan.

Layanan ini sangat berguna untuk membuat kueri alamat yang ambigu dalam sistem otomatis, dan komponen string non-alamat dapat mencocokkan bisnis serta alamat. Contoh kueri alamat yang ambigu adalah alamat yang diformat dengan buruk atau permintaan yang menyertakan komponen non-alamat seperti nama bisnis. Permintaan seperti dua contoh pertama dapat menampilkan nol hasil kecuali jika lokasi — seperti wilayah, pembatasan lokasi, atau bias lokasi — ditetapkan.

Text Search (Baru) mirip dengan Nearby Search (Baru). Perbedaan utama antara keduanya adalah Text Search (Baru) memungkinkan Anda menentukan string penelusuran arbitrer, sedangkan Nearby Search (Baru) memerlukan area tertentu untuk melakukan penelusuran.

"10 High Street, UK" atau "123 Main Street, US"	Beberapa "High Street" di Inggris Raya; beberapa "Main Street" di Amerika Serikat. Kueri tidak menampilkan hasil yang diinginkan kecuali jika batasan lokasi ditetapkan.
"ChainRestaurant New York"	Beberapa lokasi "ChainRestaurant" di New York; tidak ada alamat jalan atau bahkan nama jalan.
"10 High Street, Escher UK" atau "123 Main Street, Pleasanton US"	Hanya ada satu "High Street" di kota Escher, Inggris Raya; hanya ada satu "Main Street" di kota Pleasanton, CA, Amerika Serikat.
"UniqueRestaurantName New York"	Hanya ada satu tempat usaha dengan nama ini di New York; tidak perlu alamat jalan untuk membedakannya.
"restoran pizza di Jakarta"	Kueri ini berisi batasan lokasi, dan "restoran pizza" adalah jenis tempat yang terdefinisi dengan baik. Fungsi ini menampilkan beberapa hasil.
"[phone]"	Kueri ini berisi nomor telepon. API ini menampilkan beberapa hasil untuk tempat yang terkait dengan nomor telepon tersebut. Catatan: Untuk mendapatkan hasil terbaik saat menelusuri nomor telepon, sertakan kode negara yang diikuti dengan spasi, dan tetapkan parameter regionCode agar sesuai dengan kode negara. Format nomor telepon bervariasi menurut negara dan API mencoba menampilkan hasil untuk format yang berbeda-beda ini.

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

Permintaan Text Search

Catatan: Penelusuran Teks adalah bagian dari Places SDK for Android (Baru) dan tidak tersedia di Places SDK for Android.

Permintaan Text Search berbentuk:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

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

Dalam contoh ini, Anda:

• Tetapkan daftar kolom agar hanya menyertakan Place.Field.ID dan Place.Field.DISPLAY_NAME. Artinya, objek Place dalam respons yang merepresentasikan setiap tempat yang cocok hanya berisi dua kolom tersebut.

• Gunakan SearchByTextRequest.Builder untuk membuat objek SearchByTextRequest yang menentukan penelusuran.

  • Setel string kueri teks ke "Spicy Vegetarian Food".

  • Tetapkan jumlah maksimum tempat hasil menjadi 10. Nilai default dan maksimumnya adalah 20.

  • Membatasi area penelusuran ke persegi panjang yang ditentukan oleh koordinat lintang dan bujur. Tidak ada kecocokan di luar area ini yang ditampilkan.

• Tambahkan OnSuccessListener dan dapatkan tempat yang cocok dari objek SearchByTextResponse.

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 kelas permintaan (misalnya, FetchPlaceRequest). Pembatalan dilakukan dengan upaya terbaik. Setelah permintaan pembatalan dikeluarkan, tidak ada respons yang akan ditampilkan. Penerbitan token pembatalan TIDAK menjamin bahwa permintaan tertentu akan dibatalkan, dan Anda mungkin masih ditagih untuk permintaan tersebut meskipun tidak ada respons yang ditampilkan.

Respons Text Search

Class SearchByTextResponse mewakili respons dari permintaan penelusuran. Objek SearchByTextResponse 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:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

Daftar kolom ini berarti bahwa setiap objek Place dalam respons hanya berisi ID tempat dan nama setiap tempat yang cocok. Kemudian, Anda 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 wajib

Parameter yang diperlukan untuk SearchByTextRequest adalah:

• Daftar kolom

  Tentukan kolom data tempat yang akan ditampilkan. Teruskan daftar nilai Place.Field yang menentukan kolom data yang akan ditampilkan. Tidak ada daftar default kolom yang ditampilkan dalam respons.

  Daftar kolom adalah praktik desain yang baik untuk memastikan Anda tidak meminta data yang tidak diperlukan, sehingga membantu menghindari waktu pemrosesan dan biaya penagihan yang tidak perlu.

  Tentukan satu atau beberapa kolom berikut:

  • Kolom berikut memicu SKU Text Search Essentials ID Only:

    Place.Field.DISPLAY_NAME*
        * Gunakan sebagai pengganti Place.Field.NAME (tidak digunakan lagi di versi 4.0).
    Place.Field.ID
Place.Field.RESOURCE_NAME*
        * Berisi nama resource tempat dalam bentuk: places/PLACE_ID.
         Gunakan DISPLAY_NAME untuk mengakses nama tekstual tempat tersebut.

  • Kolom berikut memicu SKU Text Search Pro:

    Place.Field.ACCESSIBILITY_OPTIONS*
        Gunakan sebagai pengganti Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (tidak digunakan lagi).
    Place.Field.ADDRESS_COMPONENTS
Place.Field.ADR_FORMAT_ADDRESS
Place.Field.BUSINESS_STATUS
Place.Field.FORMATTED_ADDRESS*
        Gunakan sebagai pengganti Place.Field.ADDRESS (tidak digunakan lagi).
    Place.Field.GOOGLE_MAPS_URI
Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL *
        Gunakan sebagai pengganti Place.Field.ICON_URL (tidak digunakan lagi).
    Place.Field.LOCATION*
        Gunakan sebagai pengganti Place.Field.LAT_LNG (tidak digunakan lagi).
    Place.Field.PHOTO_METADATAS
Place.Field.PLUS_CODE
Place.Field.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.SHORT_FORMATTED_ADDRESS
Place.Field.SUB_DESTINATIONS
Place.Field.TYPES
Place.Field.UTC_OFFSET
Place.Field.VIEWPORT

  • Kolom berikut memicu SKU Text Search Enterprise:

    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

  • Kolom berikut memicu SKU Text Search Enterprise Plus:

    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
  Catatan: Places SDK for Android versi 4.0 memperkenalkan penghentian penggunaan beberapa kolom data Tempat dan penambahan kolom baru. Untuk mengetahui informasi selengkapnya, lihat Bermigrasi ke kolom data Tempat baru di Places SDK for Android 4.0 .

  Untuk menetapkan parameter daftar kolom, panggil metode setPlaceFields() saat membangun objek SearchByTextRequest.

• Kueri teks

  String teks yang digunakan untuk menelusuri, misalnya: "restoran", "123 Main Street", atau "tempat terbaik untuk dikunjungi di San Francisco". API akan menampilkan kandidat hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat.

  Untuk menetapkan parameter kueri teks, panggil metode setTextQuery() saat membuat objek SearchByTextRequest.

Parameter opsional

Gunakan objek SearchByTextRequest untuk menentukan parameter opsional untuk permintaan Anda.

• Jenis yang disertakan

  Membatasi hasil ke tempat yang cocok dengan jenis yang ditentukan yang ditentukan oleh Tabel A. Hanya satu jenis yang dapat ditentukan. Contoh:

  • setIncludedType("bar")
  • setIncludedType("pharmacy")
  Catatan: Nilai dalam Tabel B hanya ditampilkan dalam respons. Anda tidak dapat menggunakan nilai dalam Tabel B sebagai filter.

  Untuk menetapkan parameter jenis yang disertakan, panggil metode setIncludedType() saat membangun objek SearchByTextRequest.

• Bias lokasi

  Menentukan area yang akan ditelusuri. Lokasi ini berfungsi sebagai bias yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di luar area yang ditentukan.

  Anda dapat menentukan pembatasan lokasi atau bias lokasi, tetapi tidak keduanya. Anggap pembatasan lokasi sebagai penentuan wilayah tempat hasil harus berada, dan pembiasan lokasi sebagai penentuan wilayah tempat hasil kemungkinan akan berada atau di dekatnya — dengan mengingat bahwa saat menggunakan pembiasan lokasi, hasil masih dapat berada di luar area yang ditentukan.

  Catatan: Jika Anda tidak menyertakan bias lokasi dan pembatasan lokasi, API akan menggunakan bias IP secara default. Dengan penyesuaian IP, API menggunakan alamat IP perangkat untuk menyesuaikan hasil.
  Catatan: Parameter locationBias dapat diganti jika textQuery berisi lokasi eksplisit seperti Market in Barcelona. Dalam hal ini, locationBias diabaikan.

  Tentukan wilayah sebagai Area Tampilan persegi panjang atau sebagai lingkaran.

  • Lingkaran ditentukan oleh titik tengah dan radius dalam meter. Radius harus antara 0,0 dan 50000,0, inklusif. Contoh:

    // Define latitude and longitude coordinates of the center of the search area.
    LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);
    
    // Use the builder to create a SearchByTextRequest object.
    // Set the radius of the search area to 500.0 meters.
    final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
      .setMaxResultCount(10)
      .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();

  • Persegi panjang adalah area tampilan lintang-bujur, yang ditampilkan sebagai dua titik rendah dan tinggi yang berlawanan secara diagonal. Titik rendah menandai sudut barat daya persegi panjang, dan titik tinggi merepresentasikan sudut timur laut persegi panjang.

    Area pandang dianggap sebagai area tertutup, yang berarti area pandang mencakup batasnya. Batas lintang harus berkisar antara -90 hingga 90 derajat inklusif, dan batas bujur harus berkisar antara -180 hingga 180 derajat inklusif:

    • Jika low = high, area tampilan terdiri dari satu titik tersebut.
    • Jika low.longitude > high.longitude, rentang bujur terbalik (area tampilan melintasi garis bujur 180 derajat).
    • Jika low.longitude = -180 derajat dan high.longitude = 180 derajat, area pandang mencakup semua bujur.
    • Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujur kosong.
    • Jika low.latitude > high.latitude, rentang lintang kosong.

    Nilai rendah dan tinggi harus diisi, dan kotak yang ditampilkan tidak boleh kosong. Viewport kosong akan menyebabkan error.

    Misalnya, untuk area tampilan persegi panjang, lihat Permintaan Penelusuran Teks.

    Untuk menyetel parameter bias lokasi, panggil metode setLocationBias() saat membangun objek SearchByTextRequest.

• Pembatasan lokasi

  Menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan tidak ditampilkan. Tentukan wilayah sebagai Area Tampilan persegi panjang. Lihat deskripsi Bias lokasi untuk mengetahui informasi tentang cara menentukan Area tampilan.

  Anda dapat menentukan pembatasan lokasi atau bias lokasi, tetapi tidak keduanya. Anggap pembatasan lokasi sebagai penentuan region yang harus berada dalam hasil, dan bias lokasi sebagai penentuan region yang harus berada di dekat hasil, tetapi dapat berada di luar area.

  Catatan: Jika Anda tidak menyertakan bias lokasi dan pembatasan lokasi, API akan menggunakan bias IP secara default. Dengan penyesuaian IP, API menggunakan alamat IP perangkat untuk menyesuaikan hasil.

  Untuk menetapkan parameter pembatasan lokasi, panggil metode setLocationRestriction() saat membuat objek SearchByTextRequest.

• 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 membangun objek SearchByTextRequest.

• Nilai minimum

  Membatasi hasil hanya pada hasil yang memiliki rating pengguna rata-rata lebih besar dari atau sama dengan batas ini. Nilai harus antara 0,0 dan 5,0 (inklusif) dengan kenaikan 0,5. Misalnya: 0, 0,5, 1,0, ... , 5,0 inklusif. Nilai dibulatkan ke atas ke 0,5 terdekat. Misalnya, nilai 0,6 akan menghilangkan semua hasil dengan rating kurang dari 1,0.

  Untuk menetapkan parameter rating minimum, panggil metode setMinRating() saat membangun objek SearchByTextRequest.

• Buka sekarang

  Jika true, hanya menampilkan tempat yang buka pada saat kueri dikirim. Jika false, tampilkan semua bisnis terlepas dari status buka. Tempat yang tidak menetapkan jam buka dalam database Google Places akan ditampilkan jika Anda menetapkan parameter ini ke false.

  Untuk menetapkan parameter buka sekarang, panggil metode setOpenNow() saat membuat objek SearchByTextRequest.

• Tingkat harga

  Secara default, hasil mencakup tempat yang menyediakan layanan di semua tingkat harga. Untuk membatasi hasil agar hanya menyertakan tempat dengan tingkat harga tertentu, Anda dapat meneruskan daftar nilai bilangan bulat yang sesuai dengan tingkat harga untuk tempat yang ingin Anda tampilkan:

  • 1 - Tempat menyediakan layanan yang tidak mahal.
  • 2 - Tempat menyediakan layanan dengan harga sedang.
  • 3 - Tempat menyediakan layanan mahal.
  • 4 - Tempat menyediakan layanan yang sangat mahal.
  Catatan: Nilai bilangan bulat 0, yang menunjukkan bahwa tempat tersebut menyediakan layanan gratis, dapat disertakan dalam respons, tetapi tidak dapat digunakan sebagai nilai filter dalam permintaan.

  Untuk menetapkan parameter tingkat harga, panggil metode setPriceLevels() saat membangun objek SearchByTextRequest.

• Preferensi peringkat

  Menentukan cara peringkat hasil dalam respons berdasarkan jenis kueri:

  • Untuk kueri kategori seperti "Restoran di New York City", SearchByTextRequest.RankPreference.RELEVANCE (peringkat hasil berdasarkan relevansi penelusuran) adalah defaultnya. Anda dapat menetapkan preferensi peringkat ke SearchByTextRequest.RankPreference.RELEVANCE atau SearchByTextRequest.RankPreference.DISTANCE (peringkat hasil menurut jarak).
  • Untuk kueri non-kategoris seperti "Mountain View, CA", sebaiknya Anda membiarkan parameter preferensi peringkat tidak disetel.

  Untuk menetapkan parameter preferensi peringkat, panggil metode setRankPreference() saat membuat objek SearchByTextRequest.

• Kode wilayah

  Kode wilayah yang digunakan untuk memformat respons, ditentukan sebagai nilai kode CLDR dua karakter. Parameter ini juga dapat menimbulkan efek bias pada hasil penelusuran. Tidak ada nilai default.

  Jika nama negara di 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 "The United Kingdom of Great Britain and Northern Ireland"). Parameter dapat memengaruhi hasil berdasarkan hukum yang berlaku.

  Untuk menetapkan parameter kode wilayah, panggil metode setRegionCode() saat membuat objek SearchByTextRequest.

• Pemfilteran jenis ketat

  Digunakan dengan parameter jenis sertakan. Jika disetel ke true, hanya tempat yang cocok dengan jenis yang ditentukan oleh include type yang akan ditampilkan. Jika false, yang merupakan nilai default, respons dapat berisi tempat yang tidak cocok dengan jenis yang ditentukan.

  Untuk menyetel parameter pemfilteran jenis ketat, panggil metode setStrictTypeFiltering() saat membuat objek SearchByTextRequest.