Telusuri sepanjang rute

Alat search_along_route memungkinkan LLM menemukan tempat di sepanjang rute perjalanan dari kueri bahasa alami, seperti Stasiun Pengisian Kendaraan Listrik Umum dalam perjalanan ke Danau Tahoe atau kedai kopi antara San Francisco dan San Jose. Alat ini akan menampilkan ringkasan yang dibuat AI tentang tempat yang cocok dan konsekuensi rute memutar. Untuk setiap tempat yang dikutip dalam ringkasan, respons juga menyertakan ID tempat, koordinat lintang/bujur, link Google Maps, atribusi yang diperlukan, dan metrik rute memutar.

Setiap permintaan search_along_route adalah opsi Pro dan ditagih berdasarkan SKU Maps Grounding Pro.

Anda dapat memanggil search_along_route melalui server MCP atau sebagai metode REST searchAlongRoute. Halaman ini menjelaskan opsi permintaan, cara menentukan rute, isi respons, dan cara penagihan permintaan. Untuk skema lengkap, lihat referensi MCP search_along_route dan referensi REST searchAlongRoute.

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_along_route:

Opsi Deskripsi
text_query Wajib. Kueri penelusuran bahasa alami untuk tempat di sepanjang rute—misalnya, ev chargers, coffee, atau vegetarian restaurants.
retrieval_token, route_endpoints, atau encoded_polyline Wajib. Rute yang akan ditelusuri. Tentukan salah satu dari tiga kolom ini di setiap permintaan. Lihat Menentukan rute.
travel_mode Opsional. Mode transportasi yang digunakan untuk menghitung rute dan rute memutar: DRIVE (default), WALK, atau BICYCLE. WALK dan BICYCLE hanya didukung dengan route_endpoints. TRANSIT tidak didukung. Rute WALK masih dalam versi beta dan terkadang mungkin tidak memiliki trotoar atau jalur pejalan kaki yang jelas. Anda harus menampilkan peringatan ini kepada pengguna untuk semua rute jalan kaki yang Anda tampilkan di aplikasi.
routing_preference Opsional. Cara data lalu lintas digunakan untuk menghitung waktu rute dan rute memutar: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (default) atau ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL menggunakan kondisi lalu lintas real-time jika tersedia dan tidak didukung untuk WALK atau BICYCLE.
include_extended_details Opsional. Jika true, ringkasan akan menyertakan detail tempat yang diperluas, seperti insight dari ulasan, item menu, suasana, tips pengunjung, ketersediaan pengisi daya EV, atau harga bensin. Default-nya adalah false.
language_code Opsional. Kode bahasa BCP-47 untuk ringkasan dan jarak rute memutar yang dilokalkan—misalnya, en-US atau ja. Default-nya adalah en-US.
region_code Opsional. Kode wilayah CLDR dua huruf pengguna—misalnya, US atau CA. Memengaruhi nama tempat spesifik per wilayah dan dapat memengaruhi hasil berdasarkan hukum yang berlaku.

Menentukan rute

Setiap permintaan search_along_route harus menentukan rute menggunakan salah satu dari tiga kolom yang saling eksklusif. Menetapkan lebih dari satu kolom rute, atau menghilangkan ketiganya, akan menampilkan error INVALID_ARGUMENT.

Tabel berikut membandingkan tiga cara untuk menentukan rute:

Opsi rute Format input Mode perjalanan yang didukung Menampilkan detourDuration Kapan menggunakannya
retrieval_token String retrievalToken dari respons compute_routes sebelumnya (berlaku selama 10 menit) DRIVE Ya Agen telah memanggil compute_routes untuk rute mengemudi, termasuk rute dengan perhentian sementara, dan pengguna meminta tempat di sepanjang rute tersebut.
route_endpoints Objek dengan titik jalan origin dan destination (address, place_id, atau lat_lng) DRIVE, WALK, BICYCLE Ya Pengguna meminta untuk menemukan tempat di antara dua lokasi dalam satu langkah tanpa memanggil compute_routes terlebih dahulu, atau rute menggunakan jalan kaki atau bersepeda.
encoded_polyline String polyline yang dienkode yang mewakili rute mobil DRIVE Tidak (hanya menampilkan localizedDetourDistance) Aplikasi Anda sudah memiliki polyline rute dari sumber lain, seperti Routes API.

Chain compute_routes dan search_along_route

Saat permintaan compute_routes menggunakan mode transportasi umum DRIVE, setiap rute dalam respons menyertakan kolom retrievalToken. Token ini berlaku selama 10 menit dan mengenkode rute yang dihitung, termasuk perhentian di tengah rute. Saat pengguna menindaklanjuti dengan menanyakan tempat di sepanjang rute tersebut, LLM dapat meneruskan nilai retrievalToken sebagai retrieval_token di search_along_route.

Detail tempat yang diperluas

Tetapkan include_extended_details ke true saat permintaan pengguna memerlukan insight kualitatif, kondisi real-time, atau atribut khusus di sepanjang rute, 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 untuk pengunjung dan data real-time: apakah perlu memesan terlebih dahulu, waktu tunggu, seberapa ramai tempat tersebut, ketersediaan pengisi daya EV, harga bensin, tempat parkir, dan fasilitas.

Biarkan include_extended_details ditetapkan ke false (default) untuk penelusuran standar di sepanjang rute, seperti menemukan SPBU, tempat istirahat, atau kedai kopi berdasarkan lokasi, jam buka, dan waktu memutar. Permintaan dengan detail yang diperluas memerlukan waktu lebih lama untuk diselesaikan, tetapi tidak dikenai biaya tambahan karena setiap permintaan search_along_route sudah ditagih berdasarkan SKU Pro.

Contoh

Permintaan MCP berikut menelusuri Stasiun Pengisian Kendaraan Listrik Umum antara San Francisco dan Lake Tahoe menggunakan route_endpoints dan pemilihan rute berbasis lalu lintas:

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "fast EV chargers with a coffee shop nearby",
      "route_endpoints": {
        "origin": {"address": "San Francisco, CA"},
        "destination": {"address": "Lake Tahoe, CA"}
      },
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

Contoh berikut menggunakan retrieval_token dari respons compute_routes sebelumnya:

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "coffee shops",
      "retrieval_token": "RETRIEVAL_TOKEN"
    }
  },
  "jsonrpc": "2.0",
  "id": 2
}

Ganti RETRIEVAL_TOKEN dengan string retrievalToken yang ditampilkan oleh compute_routes.

Contoh berikut mengirimkan permintaan pertama ke metode REST searchAlongRoute:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "fast EV chargers with a coffee shop nearby",
  "routeEndpoints": {
    "origin": {"address": "San Francisco, CA"},
    "destination": {"address": "Lake Tahoe, CA"}
  },
  "travelMode": "DRIVE",
  "routingPreference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchAlongRoute"

Ganti API_KEY dengan kunci API Anda.

Respons

Respons berisi kolom berikut:

  • summary: Ringkasan bahasa alami dari hasil penelusuran dan konsekuensi rute memutar. Respons ini mungkin berisi kutipan berbasis nol, seperti [0], yang dipetakan ke entri di results.
  • results[]: Daftar tempat berperingkat yang disebutkan dalam ringkasan. Setiap entri mencakup:
    • place: Detail tentang tempat:
      • 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.
    • detourSummary: Waktu dan jarak perjalanan tambahan yang diperlukan untuk berhenti di tempat ini di sepanjang rute:
      • localizedDetourDistance: Jarak tambahan yang diformat dalam bahasa permintaan, seperti "1.2 mi" atau "1.9 km".
      • detourDuration: Waktu perjalanan tambahan sebagai string durasi, seperti "180s". Kolom ini tidak ditetapkan jika rute ditentukan dengan encoded_polyline.
  • 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.

Untuk mengetahui detail kolom selengkapnya, lihat referensi search_along_route.

Penagihan dan kuota

Setiap permintaan search_along_route adalah satu peristiwa yang dapat ditagih berdasarkan SKU Maps Grounding Pro. Menetapkan include_extended_details ke true atau routing_preference ke ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL tidak akan menambah biaya tambahan. Jika agen Anda memanggil compute_routes terlebih dahulu, lalu meneruskan retrieval_token ke search_along_route, setiap panggilan alat akan ditagih sebagai permintaan terpisah.

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

Kuota search_along_route adalah 300 kueri per menit untuk setiap project. Untuk mengetahui harga, lihat Tabel harga utama dan Tabel harga India.