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 ringkasan, ringkasan juga menampilkan ID tempat, koordinat lintang/bujur, link Google Maps, dan atribusi.

Anda dapat memanggil search_places melalui server MCP atau sebagai metode REST searchText. Halaman ini menjelaskan opsi permintaan, termasuk opsi Pro; isi respons; dan cara penagihan permintaan. Untuk skema lengkap, lihat referensi MCP search_places dan referensi REST searchText.

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.

Tabel berikut menjelaskan opsi permintaan untuk search_places:

Opsi Pro

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

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 MCP 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
}

Contoh berikut mengirimkan permintaan yang sama ke metode REST searchText:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "date night Italian restaurants in Chicago",
  "pageSize": 8,
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"

Ganti API_KEY dengan kunci API Anda.

Tanpa detail yang diperluas, ringkasan akan 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 intim dan diterangi cahaya lilin 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

Respons berisi kolom berikut:

• 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 Google Maps Platform API lainnya, seperti untuk menampilkan tempat di peta.
  • location: Koordinat lintang/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.
• contentToken: Token visualisasi data agentic (Pratinjau) yang memungkinkan Anda menampilkan tempat dalam respons dengan Kit UI Tempat tanpa biaya tambahan. Ditampilkan saat respons menyertakan setidaknya satu tempat.

Respons memiliki struktur yang sama untuk SKU serta untuk MCP dan REST. Untuk mengetahui detail kolom, lihat referensi search_places.

Penagihan dan kuota

Setiap permintaan search_places adalah satu peristiwa yang dapat ditagih:

• Permintaan yang tidak menggunakan opsi Pro akan ditagih berdasarkan SKU Maps Grounding Essentials.
• Permintaan yang menggunakan opsi Pro akan ditagih berdasarkan SKU Maps Grounding Pro. Menggunakan kedua opsi dalam satu permintaan tidak akan mengubah biaya. Untuk mengetahui harga Pro, lihat Membandingkan Essentials, Pro, dan Grounding with Google Maps.

Jika Anda menampilkan tempat dari respons search_places dengan Places UI Kit, Anda dapat menggunakan token visualisasi data agentic (Pratinjau) agar permintaan Places UI Kit tersebut tidak ditagih.

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