MCP Tools Reference: mapstools.googleapis.com

Alat: search_along_route

Panggil alat ini saat pengguna ingin menemukan tempat, bisnis, atau lokasi menarik di sepanjang rute perjalanan (misalnya, "pom bensin dalam perjalanan ke Tahoe", "kedai kopi antara SF dan San Jose"). Memanggil alat ini memerlukan biaya yang lebih tinggi daripada search_places, jadi gunakan search_places saat menelusuri di dekat satu lokasi, bukan di sepanjang rute.

Persyaratan Input (PENTING):

  1. text_query (string - WAJIB): Deskripsi bahasa alami tentang apa yang harus ditelusuri di sepanjang rute.

    • Contoh: 'ev chargers', 'coffee', 'vegetarian restaurants', 'rest stops'.

  2. Spesifikasi rute (WAJIB - berikan tepat SATU dari hal berikut):

    • retrieval_token (string): retrieval_token yang ditampilkan oleh panggilan compute_routes sebelumnya untuk rute DRIVE. Pilih opsi ini setiap kali rute sudah dihitung. Token ini berlaku selama 10 menit.
    • route_endpoints (objek): origin dan destination rute. Masing-masing harus disediakan menggunakan salah satu dari address, lat_lng, atau place_id.
      • Contoh: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
    • encoded_polyline (string): Polyline yang dienkode yang mewakili rute DRIVE.

  3. travel_mode (enum - OPSIONAL): DRIVE (default), WALK, atau BICYCLE. WALK dan BICYCLE hanya didukung dengan route_endpoints. TRANSIT tidak didukung.

  4. routing_preference (enum - OPSIONAL):

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (default): menghitung rute dan rute memutar tanpa lalu lintas real-time. Latensi terendah.
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: menggunakan kondisi lalu lintas real-time jika tersedia. Tidak didukung untuk WALK atau BICYCLE. Setel ini HANYA jika pengguna bertanya tentang lalu lintas, kemacetan, atau waktu rute alternatif yang disesuaikan dengan lalu lintas. Hal ini menimbulkan latensi yang lebih tinggi.

  5. include_extended_details (boolean - OPSIONAL): Tetapkan ke true hanya jika permintaan memerlukan insight ulasan kualitatif, item menu atau penawaran tertentu, suasana, tips atau tingkat kesibukan pengunjung, ketersediaan pengisi daya EV, harga bensin, atau detail kualitatif lengkap lainnya. Defaultnya adalah false. Mengaktifkannya dapat meningkatkan latensi.

  6. language_code (string - OPSIONAL): Bahasa untuk ringkasan hasil dan detail tempat, misalnya, en, ja, en-US. Nilai defaultnya adalah en-US.

  7. region_code (string - OPSIONAL): Kode wilayah CLDR Unicode pengguna, misalnya, US, CA.

Instructions for Tool Call:

  • Setiap hasil menyertakan detour_summary (jika tersedia) yang menjelaskan jarak tambahan (localized_detour_distance) dan, kecuali jika rute diberikan sebagai encoded_polyline, waktu tambahan (detour_duration) yang diperlukan untuk berhenti di tempat tersebut. Gunakan untuk membandingkan opsi.
  • Respons summary dapat berisi kutipan berbasis nol (misalnya, "[0]") yang merujuk ke entri di results.
  • Output yang di-grounding harus diatribusikan ke sumber menggunakan kolom attribution dari setiap results[].place jika tersedia.

Contoh kode berikut menunjukkan cara menggunakan curl untuk memanggil alat MCP search_along_route.

Permintaan Curl 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Skema Input

Pesan permintaan untuk SearchAlongRoute.

SearchAlongRouteRequest

Representasi JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "routingPreference": enum (RoutingPreference),
  "includeExtendedDetails": boolean,
  "travelMode": enum (RouteTravelMode),

  // Union field route_spec can be only one of the following:
  "encodedPolyline": string,
  "retrievalToken": string,
  "routeEndpoints": {
    object (RouteEndpoints)
  }
  // End of list of possible types for union field route_spec.
}
Kolom
textQuery

string

Wajib. Kueri penelusuran bahasa alami (misalnya, "pengisi daya kendaraan listrik", "kopi").
languageCode

string

Opsional. Bahasa untuk ringkasan dan detail tempat. Default-nya adalah "en-US".
regionCode

string

Opsional. Kode negara/wilayah (CLDR) lokasi (misalnya, "US").
routingPreference

enum (RoutingPreference)

Opsional. Preferensi pemilihan rute opsional yang menentukan cara penggunaan data lalu lintas. Nilai defaultnya adalah TRAFFIC_UNAWARE.
includeExtendedDetails

boolean

Opsional. Menyertakan detail tempat yang diperluas dalam respons.

Tetapkan kolom ini ke true jika permintaan pengguna memerlukan insight kualitatif yang lengkap, dinamika real-time, atau atribut entitas khusus: - Ulasan kualitatif, sentimen pelanggan, dan masukan. - Penawaran spesifik seperti item menu, hidangan, makanan khas, minuman, atau keunggulan bisnis. - Suasana, dekorasi interior, estetika, nuansa, atau mood kualitatif. - Data real-time dan spesifikasi fasilitas khusus, kebijakan/tips pengunjung, waktu tunggu.

Biarkan false (default) untuk penelusuran penemuan standar (misalnya, masakan, jenis toko), pencarian lokasi/alamat, info kontak, jam buka, dan metadata/fasilitas standar.

Mengaktifkan kolom ini dapat menimbulkan latensi yang lebih tinggi.
travelMode

enum (RouteTravelMode)

Opsional. Menentukan mode perjalanan yang digunakan untuk menghitung rute dan rute memutar. Default-nya adalah DRIVE. WALK dan BICYCLE hanya didukung dengan route_endpoints. TRANSIT tidak didukung.
Kolom union route_spec. Spesifikasi rute: rute yang ada, token rute, atau endpoint asal/tujuan. route_spec hanya dapat berupa salah satu dari berikut:
encodedPolyline

string

String polyline yang dienkode yang mewakili rute. Lihat https://developers.google.com/maps/documentation/utilities/polylinealgorithm
retrievalToken

string

Token pengambilan yang ditampilkan dari panggilan ComputeRoutes sebelumnya yang mewakili rute.
routeEndpoints

object (RouteEndpoints)

Endpoint rute eksplisit (asal dan tujuan).

RouteEndpoints

Representasi JSON 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  }
}
Kolom
origin

object (Waypoint)

Wajib. Titik awal (alamat, ID Tempat, atau koordinat geografis).
destination

object (Waypoint)

Wajib. Titik tujuan (alamat, ID Tempat, atau koordinat geografis).

Waypoint

Representasi JSON 
{

  // Union field location_type can be only one of the following:
  "latLng": {
    object (LatLng)
  },
  "placeId": string,
  "address": string
  // End of list of possible types for union field location_type.
}
Kolom
Kolom union location_type. Berbagai cara untuk merepresentasikan lokasi. location_type hanya dapat berupa salah satu dari berikut:
latLng

object (LatLng)

Titik yang ditentukan menggunakan koordinat geografis.
placeId

string

ID Tempat yang terkait dengan titik jalan.
address

string

Alamat yang dapat dibaca manusia atau plus code. Lihat https://plus.codes untuk mengetahui detailnya.

LatLng

Representasi JSON 
{
  "latitude": number,
  "longitude": number
}
Kolom
latitude

number

Lintang dalam derajat. Harus dalam rentang [-90.0, +90.0].
longitude

number

Bujur dalam derajat. Harus dalam rentang [-180.0, +180.0].

RoutingPreference

Serangkaian nilai yang menentukan faktor yang perlu dipertimbangkan saat menghitung rute.

Enum
ROUTING_PREFERENCE_UNSPECIFIED Tidak ada preferensi pemilihan rute yang ditentukan. Default-nya adalah ROUTING_PREFERENCE_TRAFFIC_UNAWARE.
ROUTING_PREFERENCE_TRAFFIC_UNAWARE Menghitung rute tanpa mempertimbangkan kondisi lalu lintas real-time. Cocok jika kondisi lalu lintas tidak penting atau tidak berlaku. Penggunaan nilai ini akan menghasilkan latensi terendah.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

Menghitung rute dengan mempertimbangkan kondisi lalu lintas real-time, jika data lalu lintas tersedia. Untuk TRANSIT, menggunakan data transportasi umum real-time, seperti keterlambatan dan pembatalan, jika tersedia.

Nilai ini akan memicu paket Pro dan menimbulkan biaya yang ditagih serta latensi yang lebih tinggi.

RouteTravelMode

Kumpulan nilai yang digunakan untuk menentukan mode perjalanan.

Enum
ROUTE_TRAVEL_MODE_UNSPECIFIED Tidak ada mode perjalanan yang ditentukan. Default-nya adalah DRIVE.
DRIVE Bepergian dengan mobil penumpang.
WALK Bepergian dengan berjalan kaki. CATATAN: 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.
BICYCLE Bepergian dengan sepeda.
TRANSIT Bepergian dengan transportasi umum.

Skema Output

Pesan respons untuk SearchAlongRoute.

SearchAlongRouteResponse

Representasi JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "summary": string,
  "contentToken": string
}
Kolom
results[]

object (Result)

Hanya output. Daftar hasil penelusuran yang diurutkan berdasarkan peringkat yang ditemukan di sepanjang rute.
summary

string

Hanya output. Ringkasan bahasa alami dari hasil penelusuran dan konsekuensi rute memutar. Dapat berisi kutipan berbasis nol (misalnya "[0]", "[1]") yang merujuk ke entri yang sesuai dalam daftar results.
contentToken

string

Hanya output. Token terenkripsi yang mengenkapsulasi konteks penelusuran dan dapat diteruskan ke layanan rendering visual Google Maps, SDK, atau Maps Agentic UI Toolkit (A2UI) untuk menampilkan komponen UI interaktif untuk hasil penelusuran yang ditampilkan.

Hasil

Representasi JSON 
{
  "place": {
    object (PlaceView)
  },
  "detourSummary": {
    object (DetourSummary)
  }
}
Kolom
place

object (PlaceView)

Hanya output. Detail tentang tempat yang ditemukan di sepanjang rute.
detourSummary

object (DetourSummary)

Hanya output. Metrik rute memutar yang timbul karena menambahkan tempat ini sebagai perhentian sementara di sepanjang rute. Dihilangkan atau kosong jika metrik rute memutar tidak dapat dihitung.

PlaceView

Representasi JSON 
{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },
  "attribution": {
    object (Attribution)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field _location.
}
Kolom
place

string

Nama resource tempat yang mendasarinya, dalam format "places/{id}".
id

string

ID tempat dari tempat yang mendasarinya.
googleMapsLinks

object (GoogleMapsLinks)

Link untuk memicu berbagai tindakan Google Maps.
attribution

object (Attribution)

Atribusi yang diperlukan untuk ditampilkan bersama tempat.

Kolom union _location.

_location hanya dapat berupa salah satu dari hal berikut:
location

object (LatLng)

Posisi tempat ini.

LatLng

Representasi JSON 
{
  "latitude": number,
  "longitude": number
}
Kolom
latitude

number

Lintang dalam derajat. Harus dalam rentang [-90.0, +90.0].
longitude

number

Bujur dalam derajat. Harus dalam rentang [-180.0, +180.0].
Representasi JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
Kolom
directionsUrl

string

Link untuk menampilkan rute ke tempat tersebut. Link hanya mengisi lokasi tujuan dan menggunakan mode perjalanan default DRIVE.
placeUrl

string

Link untuk menampilkan tempat ini.
writeAReviewUrl

string

Link untuk menulis ulasan untuk tempat ini di Google Maps.
reviewsUrl

string

Link untuk menampilkan ulasan tempat ini di Google Maps.
photosUrl

string

Link untuk menampilkan foto tempat ini di Google Maps.

Atribusi

Representasi JSON 
{
  "title": string,
  "url": string
}
Kolom
title

string

Judul yang akan ditampilkan untuk atribusi.
url

string

URL yang akan ditautkan untuk atribusi.

DetourSummary

Representasi JSON 
{
  "detourDuration": string,
  "localizedDetourDistance": string
}
Kolom
detourDuration

string (Duration format)

Waktu perjalanan tambahan yang diperlukan untuk memutar ke tempat ini dari rute utama. Nilai ini tidak ditetapkan jika rute ditentukan oleh encoded_polyline.

Durasi dalam detik dengan maksimal sembilan digit pecahan, diakhiri dengan 's'. Contoh: "3.5s".
localizedDetourDistance

string

Jarak tambahan yang diperlukan untuk memutar ke tempat ini dari rute utama, yang diformat untuk ditampilkan dalam bahasa permintaan (misalnya, "1,2 mi" atau "1,9 km").

Durasi

Representasi JSON 
{
  "seconds": string,
  "nanos": integer
}
Kolom
seconds

string (int64 format)

Detik bertanda dari rentang waktu. Harus dari -315.576.000.000 hingga +315.576.000.000 inklusif. Catatan: batas ini dihitung dari: 60 dtk/mnt * 60 mnt/jam * 24 jam/hari * 365,25 hari/tahun * 10.000 tahun
nanos

integer

Pecahan detik bertanda tangan pada resolusi nanodetik dari rentang waktu. Durasi kurang dari satu detik direpresentasikan dengan kolom seconds 0 dan kolom nanos positif atau negatif. Untuk durasi satu detik atau lebih, nilai bukan nol untuk kolom nanos harus memiliki tanda yang sama dengan kolom seconds. Harus dari -999.999.999 hingga +999.999.999 inklusif.

Anotasi Alat

Anotasi alat dikirim ke klien MCP untuk menjelaskan risiko dasar alat tertentu. Sebagian besar klien memperlakukan petunjuk ini sebagai tidak tepercaya, tetapi petunjuk tersebut dapat digunakan untuk memutuskan kapan perintah konfirmasi dapat dikirim kepada pengguna.

Bersama dengan string judul, petunjuk boolean berikut ditentukan sebagai berikut:

  • readOnlyHint: Jika benar, alat tidak akan mengubah lingkungannya. Default: false.
  • destructiveHint: Jika benar, alat dapat melakukan tindakan destruktif. Jika salah, alat hanya dapat melakukan tindakan aditif. Default: true.
  • idempotentHint: Jika benar, memanggil alat berulang kali dengan argumen yang sama tidak akan memberikan efek tambahan pada lingkungannya. Default: false.
  • openWorldHint: Jika benar, alat dapat berinteraksi dengan 'open world' entitas eksternal. Jika salah, alat hanya dapat berinteraksi dengan entity internal. Misalnya, alat penelusuran web akan bersifat open world, sedangkan alat memori tidak akan bersifat open world.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌