Telusuri tempat

Alat search_places memungkinkan LLM menemukan tempat di Google Maps dari kueri bahasa alami. Alat ini akan menampilkan ringkasan tempat yang cocok yang dibuat AI. Untuk setiap tempat yang dikutip dalam ringkasan, ID Tempat, koordinat, link Google Maps, dan atribusi juga ditampilkan.

Halaman ini menjelaskan opsi permintaan, termasuk opsi Pro; isi respons; dan cara permintaan ditagih. Untuk mengetahui skema alat lengkap, lihat referensi search_places.

Opsi permintaan

LLM menetapkan opsi ini saat memanggil alat, berdasarkan permintaan pengguna dan deskripsi alat. Anda dapat memengaruhi opsi yang digunakan model dengan petunjuk Anda sendiri; lihat Mengontrol penggunaan Pro.

Opsi Deskripsi
text_query Wajib. Kueri penelusuran, misalnya coffee shops near Golden Gate Park. Kueri harus berisi informasi lokasi yang cukup agar tidak ambigu, atau permintaan harus menyertakan location_bias.
location_bias Lingkaran (center dan radius_meters opsional, hingga 50.000 meter) untuk membiaskan hasil. Jika text_query menyebutkan lokasi eksplisit, lokasi tersebut akan digunakan.
language_code Bahasa ringkasan, misalnya en atau ja. Default-nya adalah bahasa Inggris.
region_code Kode wilayah CLDR pengguna, misalnya US. Memengaruhi nama tempat spesifik per wilayah dan dapat memengaruhi hasil berdasarkan hukum yang berlaku.
page_size Jumlah maksimum tempat yang akan ditampilkan. Defaultnya adalah 5. Nilai dari 6 hingga 10 adalah opsi Pro. Nilai di atas 10 akan menampilkan error INVALID_ARGUMENT. Layanan mungkin menampilkan lebih sedikit tempat daripada yang diminta.
include_extended_details Jika true, ringkasan akan menyertakan detail tempat yang diperluas. Ini adalah opsi Pro. Defaultnya adalah false.

Opsi Pro

Dua opsi memilih SKU Pro. Permintaan yang menggunakan salah satu atau keduanya akan ditagih berdasarkan SKU Pro:

Opsi Pro Kapan menggunakannya
include_extended_details disetel ke true Permintaan pengguna memerlukan detail tempat yang diperluas, seperti insight dari ulasan, sorotan menu, suasana, atau tips pengunjung.
page_size dari 6 hingga 10 Pengguna ingin membandingkan lebih dari 5 tempat.

Permintaan yang tidak menggunakan salah satu opsi, termasuk permintaan dengan page_size dari 1 hingga 5, akan ditagih berdasarkan SKU Essentials.

Detail tempat yang diperluas

Tetapkan include_extended_details ke true saat permintaan pengguna memerlukan insight kualitatif, kondisi real-time, atau atribut khusus, seperti:

  • Pendapat pengulas: insight berbasis ulasan, sentimen pelanggan, dan masukan.
  • Penawaran spesifik: item menu, hidangan, makanan khas, minuman, atau sorotan bisnis.
  • Suasana: dekorasi interior, estetika, suasana, atau mood.
  • Tips praktis bagi pengunjung: apakah perlu memesan terlebih dahulu, kebijakan kedatangan langsung, waktu tunggu, tingkat kesibukan tempat, parkir, dan fasilitas.
  • Kedekatan: jarak atau waktu perjalanan dari lokasi kueri, atau pusat location_bias, saat pengguna menanyakan apa yang ada di sekitar atau yang terdekat.

Insight dalam ringkasan bergantung pada kueri dan data yang tersedia untuk setiap tempat. Tidak semua jenis insight muncul di setiap respons.

Biarkan false (default) untuk penelusuran standar: masakan atau jenis toko, alamat, informasi kontak, jam buka, dan fasilitas standar. Permintaan dengan detail yang diperluas memerlukan waktu lebih lama untuk diselesaikan.

Detail yang diperluas tidak mengubah struktur respons. Tanpa parameter tersebut, ringkasan akan menjelaskan setiap tempat dalam satu atau dua kalimat. Dengan ringkasan ini, setiap tempat mendapatkan deskripsi yang lebih panjang yang memanfaatkan lebih banyak data Google Maps, termasuk insight dari ulasan. Entri places terstruktur sama untuk kedua SKU.

Contoh

Permintaan berikut meminta hingga 8 tempat dengan detail yang diperluas. Layanan ini ditagih berdasarkan SKU Pro:

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

Tanpa detail yang diperluas, ringkasan menjelaskan setiap tempat dalam satu atau dua kalimat:

Example Trattoria [0] (4,6★ (1.250) · 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) Ruang makan yang diterangi cahaya lilin dan intim yang digambarkan oleh pengulas sebagai romantis, tetapi bising pada akhir pekan. Hidangan yang paling populer meliputi tagliatelle al ragù, burrata, dan tiramisu. Sebaiknya lakukan reservasi; pelanggan yang datang langsung dapat menunggu selama 30–45 menit pada Jumat dan Sabtu malam, dan tempat parkir di pinggir jalan terbatas.

Respons

Responsnya berisi:

  • summary: Ringkasan hasil penelusuran dalam bahasa alami. Respons ini mungkin berisi kutipan berbasis nol, seperti [0], yang dipetakan ke entri di places.
  • places[]: Tempat yang disebutkan dalam ringkasan. Setiap tempat mencakup:
    • place: Nama resource tempat, dalam format places/{id}.
    • id: ID Tempat. Anda dapat menggunakannya dengan API Google Maps Platform lainnya, misalnya untuk menampilkan tempat di peta.
    • location: Lintang dan bujur tempat.
    • googleMapsLinks: Link Google Maps untuk tempat (placeUrl), rute (directionsUrl), ulasan (reviewsUrl), foto (photosUrl), dan menulis ulasan (writeAReviewUrl).
    • attribution: Atribusi yang harus Anda tampilkan bersama tempat. Lihat Persyaratan atribusi.

Respons memiliki struktur yang sama untuk kedua SKU. Untuk mengetahui detail kolom, lihat referensi search_places.

Opsi Pro selama GA Terbatas

Selama GA Terbatas, opsi Pro hanya tersedia untuk project dalam daftar yang diizinkan Pro. Jika project Anda belum ada dalam daftar yang diizinkan, opsi Pro akan diabaikan, bukan ditolak:

  • include_extended_details diperlakukan sebagai false.
  • Nilai page_size di atas 5, termasuk nilai di atas 10, akan dikurangi menjadi 5.

Permintaan ditagih berdasarkan SKU Essentials. Untuk meminta akses, lihat Opsi Pro selama GA Terbatas.

Penagihan dan kuota

Setiap permintaan search_places adalah satu peristiwa yang dapat ditagih:

Kuota search_places adalah 300 kueri per menit, per project, yang digunakan bersama oleh kedua SKU. Untuk mengetahui harga, lihat Tabel harga utama dan Tabel harga India.