MCP Tools Reference: mapstools.googleapis.com

Araç: search_along_route

Kullanıcı bir seyahat rotası üzerindeki yerleri, işletmeleri veya önemli noktaları bulmak istediğinde bu aracı çağırın (ör. "Tahoe'ya giderken yolumun üzerindeki benzin istasyonları", "SF ile San Jose arasındaki kafeler"). Bu aracın çağrılması search_places aracından daha yüksek maliyetlidir. Bu nedenle, bir rota yerine tek bir konumun yakınında arama yaparken search_places aracını kullanın.

Giriş Şartları (KRİTİK):

  1. text_query (dize - ZORUNLU): Rota boyunca aranacak öğelerin doğal dilde açıklaması.

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

  2. Rota spesifikasyonu (ZORUNLU - Aşağıdakilerden tam olarak BİRİNİ sağlayın):

    • retrieval_token (dize): DRIVE rotası için önceki bir compute_routes çağrısı tarafından döndürülen retrieval_token. Rota zaten hesaplanmışsa bu seçeneği tercih edin. Jeton 10 dakika boyunca geçerlidir.
    • route_endpoints (nesne): Rotanın origin ve destination değeri. Her biri address, lat_lng veya place_id kullanılarak sağlanmalıdır.
      • Örnek: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
    • encoded_polyline (dize): DRIVE rotasını temsil eden kodlanmış bir çoklu çizgi.

  3. travel_mode (enum - İSTEĞE BAĞLI): DRIVE (varsayılan), WALK veya BICYCLE. WALK ve BICYCLE yalnızca route_endpoints ile desteklenir. TRANSIT desteklenmiyor.

  4. routing_preference (enum - İSTEĞE BAĞLI):

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (varsayılan): Rotayı ve alternatif rotaları canlı trafik olmadan hesaplar. En düşük gecikme.
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: Mümkün olduğunda canlı trafik koşullarını kullanır. WALK veya BICYCLE için desteklenmez. Bu ayarı YALNIZCA kullanıcı trafik, yoğunluk veya trafiğe göre ayarlanmış alternatif rota süreleri hakkında soru sorduğunda kullanın. Daha yüksek gecikmeye neden olur.

  5. include_extended_details (Boole - İSTEĞE BAĞLI): Yalnızca istekte nitel inceleme analizleri, belirli menü öğeleri veya teklifler, atmosfer, ziyaretçi ipuçları ya da yoğunluk, EV şarj cihazı kullanılabilirliği, benzin fiyatları veya diğer zengin nitel ayrıntılar gerektiğinde true olarak ayarlanır. Varsayılan değer false'dir. Bu ayarın etkinleştirilmesi gecikmeyi artırabilir.

  6. language_code (dize - İSTEĞE BAĞLI): Sonuç özeti ve yer ayrıntıları için dil (ör. en, ja, en-US). Varsayılan değer en-US'dir.

  7. region_code (dize - İSTEĞE BAĞLI): Kullanıcının Unicode CLDR bölge kodu (ör. US, CA).

Araç Çağrısı Talimatları:

  • Her sonuç, o yerde durmanın neden olduğu ek mesafeyi (localized_detour_distance) ve rota encoded_polyline olarak verilmediği sürece ek süreyi (detour_duration) açıklayan bir detour_summary (mümkün olduğunda) içerir. Seçenekleri karşılaştırmak için bu özelliği kullanabilirsiniz.
  • summary yanıtı, results içindeki girişlere referans veren sıfır tabanlı alıntılar (ör. "[0]") içerebilir.
  • Temellendirilmiş çıkış, mümkün olduğunda her results[].place öğesinin attribution alanı kullanılarak kaynağa atfedilmelidir.

Aşağıdaki kod örneğinde, search_along_route MCP aracını çağırmak için curl öğesinin nasıl kullanılacağı gösterilmektedir.

Curl İsteği 
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
}'

Giriş şeması

SearchAlongRoute için istek mesajı.

SearchAlongRouteRequest

JSON gösterimi 
{
  "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.
}
Alanlar
textQuery

string

Zorunlu. Doğal dilde arama sorgusu (ör. "EV şarj cihazları", "kahve").
languageCode

string

İsteğe bağlı. Özet ve yer ayrıntıları için dil. Varsayılan değer "en-US"tir.
regionCode

string

İsteğe bağlı. Konumun ülke/bölge kodu (CLDR) (ör. "US").
routingPreference

enum (RoutingPreference)

İsteğe bağlı. Trafik verilerinin nasıl kullanılacağını belirten isteğe bağlı rota tercihi. Varsayılan olarak TRAFFIC_UNAWARE değerine ayarlanır.
includeExtendedDetails

boolean

İsteğe bağlı. Yanıta genişletilmiş yer ayrıntılarını ekler.

Kullanıcı isteği; niteliksel analizler, gerçek zamanlı dinamikler veya özel varlık özellikleri gerektirdiğinde bu alanı true olarak ayarlayın: - Niteliksel incelemeler, müşteri yaklaşımı ve geri bildirimler. - Menü öğeleri, yemekler, özel yemekler, içecekler veya işletmeyle ilgili öne çıkanlar gibi belirli teklifler. - Nitelikli atmosfer, iç mekan dekoru, estetik, ambiyans veya ruh hali. - Gerçek zamanlı veriler ve özel tesis özellikleri, ziyaretçi politikaları/ipuçları, bekleme süreleri.

Standart keşif aramaları (ör. mutfaklar, mağaza türleri), konum/adres aramaları, iletişim bilgileri, çalışma saatleri ve standart meta veriler/olanaklar için false (varsayılan) değerini bırakın.

Bu alanın etkinleştirilmesi daha yüksek gecikmeye neden olabilir.
travelMode

enum (RouteTravelMode)

İsteğe bağlı. Rotayı ve alternatif rotaları hesaplamak için kullanılan seyahat modunu belirtir. Varsayılan değer DRIVE'dir. WALK ve BICYCLE yalnızca route_endpoints ile desteklenir. TRANSIT desteklenmiyor.
route_spec birleşik alanı. Rota spesifikasyonu: Mevcut bir rota, rota jetonu veya başlangıç/varış noktası uç noktaları. route_spec aşağıdakilerden yalnızca biri olabilir:
encodedPolyline

string

Rotayı temsil eden kodlanmış bir çoklu çizgi dizesi. https://developers.google.com/maps/documentation/utilities/polylinealgorithm adresini inceleyin.
retrievalToken

string

Önceki bir ComputeRoutes çağrısından döndürülen ve rotayı temsil eden bir alma jetonu.
routeEndpoints

object (RouteEndpoints)

Açık rota uç noktaları (başlangıç ve varış noktası).

RouteEndpoints

JSON gösterimi 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  }
}
Alanlar
origin

object (Waypoint)

Zorunlu. Başlangıç noktası (adres, yer kimliği veya coğrafi koordinatlar).
destination

object (Waypoint)

Zorunlu. Varış noktası (adres, yer kimliği veya coğrafi koordinatlar).

Ara nokta

JSON gösterimi 
{

  // 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.
}
Alanlar
location_type birleşik alanı. Bir konumu temsil etmenin farklı yolları. location_type aşağıdakilerden yalnızca biri olabilir:
latLng

object (LatLng)

Coğrafi koordinatlar kullanılarak belirtilen bir nokta.
placeId

string

Ara nokta ile ilişkili yer kimliği.
address

string

Kullanıcıların okuyabileceği adres veya Plus Code. Ayrıntılar için https://plus.codes adresini ziyaret edin.

LatLng

JSON gösterimi 
{
  "latitude": number,
  "longitude": number
}
Alanlar
latitude

number

Derece cinsinden enlem. [-90,0, +90,0] aralığında olmalıdır.
longitude

number

Derece cinsinden boylam. [-180,0, +180,0] aralığında olmalıdır.

RoutingPreference

Rota hesaplanırken dikkate alınacak faktörleri belirten bir değerler kümesi.

Sıralamalar
ROUTING_PREFERENCE_UNSPECIFIED Yönlendirme tercihi belirtilmedi. Varsayılan değer ROUTING_PREFERENCE_TRAFFIC_UNAWARE'dir.
ROUTING_PREFERENCE_TRAFFIC_UNAWARE Canlı trafik koşullarını dikkate almadan rotaları hesaplar. Trafik koşullarının önemli veya geçerli olmadığı durumlarda uygundur. Bu değer kullanıldığında en düşük gecikme süresi elde edilir.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

Trafik verileri mevcut olduğunda canlı trafik koşullarını dikkate alarak rotaları hesaplar. TRANSIT için, gecikmeler ve iptaller gibi gerçek zamanlı toplu taşıma verilerini (varsa) kullanır.

Bu değer, Pro katmanını tetikler ve daha yüksek faturalandırma maliyeti ile gecikmeye neden olur.

RouteTravelMode

Seyahat modunu belirtmek için kullanılan bir değerler kümesi.

Sıralamalar
ROUTE_TRAVEL_MODE_UNSPECIFIED Seyahat modu belirtilmedi. Varsayılan değer DRIVE'dir.
DRIVE Binek otomobille seyahat
WALK Yürüyerek seyahat edin. NOT: WALK rotaları beta sürümündedir ve bazen net kaldırımlar veya yaya yolları eksik olabilir. Uygulamanızda gösterdiğiniz tüm yürüyüşler için kullanıcıya bu uyarıyı göstermeniz gerekir.
BICYCLE Bisikletle seyahat edin.
TRANSIT Toplu taşıma ile seyahat edin.

Çıkış şeması

SearchAlongRoute için yanıt mesajı.

SearchAlongRouteResponse

JSON gösterimi 
{
  "results": [
    {
      object (Result)
    }
  ],
  "summary": string,
  "contentToken": string
}
Alanlar
results[]

object (Result)

Yalnızca çıkış. Rota boyunca bulunan arama sonuçlarının sıralı listesi.
summary

string

Yalnızca çıkış. Arama sonuçlarının ve rota değişikliğiyle ilgili avantaj ve dezavantajların doğal dilde özeti. results listesindeki ilgili girişlere referans veren sıfır tabanlı alıntılar (ör. "[0]", "[1]") içerebilir.
contentToken

string

Yalnızca çıkış. Arama bağlamını kapsayan ve döndürülen arama sonuçları için etkileşimli kullanıcı arayüzü bileşenlerini görüntülemek üzere Google Haritalar görsel oluşturma hizmetlerine, SDK'larına veya Haritalar ajan tabanlı kullanıcı arayüzü araç setine (A2UI) iletilebilen şifrelenmiş bir jeton.

Sonuç

JSON gösterimi 
{
  "place": {
    object (PlaceView)
  },
  "detourSummary": {
    object (DetourSummary)
  }
}
Alanlar
place

object (PlaceView)

Yalnızca çıkış. Rota üzerinde bulunan yerle ilgili ayrıntılar.
detourSummary

object (DetourSummary)

Yalnızca çıkış. Bu yerin rotaya ara durak olarak eklenmesiyle oluşan rota değişikliği metrikleri. Sapma metrikleri hesaplanamadıysa atlanır veya boş bırakılır.

PlaceView

JSON gösterimi 
{
  "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.
}
Alanlar
place

string

Temel yerin "places/{id}" biçimindeki kaynak adı.
id

string

Temel yerin yer kimliği.
googleMapsLinks

object (GoogleMapsLinks)

Farklı Google Haritalar işlemlerini tetikleyen bağlantılar.
attribution

object (Attribution)

Yerle birlikte gösterilmesi gereken atıf.

_location birleşik alanı.

_location aşağıdakilerden yalnızca biri olabilir:
location

object (LatLng)

Bu yerin konumu.

LatLng

JSON gösterimi 
{
  "latitude": number,
  "longitude": number
}
Alanlar
latitude

number

Derece cinsinden enlem. [-90,0, +90,0] aralığında olmalıdır.
longitude

number

Derece cinsinden boylam. [-180,0, +180,0] aralığında olmalıdır.
JSON gösterimi 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
Alanlar
directionsUrl

string

Yere giden yol tarifini gösteren bir bağlantı. Bağlantı yalnızca hedef konumu doldurur ve varsayılan seyahat modunu DRIVE kullanır.
placeUrl

string

Bu yeri gösteren bir bağlantı.
writeAReviewUrl

string

Google Haritalar'da bu yerle ilgili yorum yazma bağlantısı.
reviewsUrl

string

Bu yerle ilgili yorumları Google Haritalar'da gösteren bir bağlantı.
photosUrl

string

Bu yerin fotoğraflarını Google Haritalar'da gösteren bir bağlantı.

İlişkilendirme

JSON gösterimi 
{
  "title": string,
  "url": string
}
Alanlar
title

string

İlişkilendirme için gösterilecek başlık.
url

string

İlişkilendirme için bağlantı verilecek URL.

DetourSummary

JSON gösterimi 
{
  "detourDuration": string,
  "localizedDetourDistance": string
}
Alanlar
detourDuration

string (Duration format)

Ana rotadan bu yere sapmak için gereken ek seyahat süresi. Rota encoded_polyline tarafından belirtilmişse bu değer ayarlanmaz.

En fazla dokuz kesirli basamak içeren ve "s" ile biten, saniye cinsinden süre. Örnek: "3.5s".
localizedDetourDistance

string

Ana rotadan bu yere gitmek için gereken ek mesafe. İstek dilinde gösterilecek şekilde biçimlendirilir (ör. "1, 2 mil" veya "1,9 km").

Süre

JSON gösterimi 
{
  "seconds": string,
  "nanos": integer
}
Alanlar
seconds

string (int64 format)

Zaman aralığının işaretli saniyeleri. -315.576.000.000 ile +315.576.000.000 arasında (her iki değer de dahil) olmalıdır. Not: Bu sınırlar şu şekilde hesaplanır: 60 sn./dk. * 60 dk./sa. * 24 sa./gün * 365,25 gün/yıl * 10.000 yıl
nanos

integer

Zaman aralığının nanosaniye çözünürlüğünde saniyenin işaretli kesirleri. Bir saniyeden kısa süreler 0 seconds alanı ve pozitif veya negatif nanos alanı ile temsil edilir. Bir saniye veya daha uzun süreler için nanos alanının sıfır olmayan değeri, seconds alanıyla aynı işarete sahip olmalıdır. -999.999.999 ile +999.999.999 arasında (her iki değer de dahil) olmalıdır.

Araç Notları

Araç ek açıklamaları, belirli bir aracın temel riskini açıklamak için MCP istemcilerine gönderilir. Çoğu istemci bu ipuçlarını güvenilir olarak değerlendirmez ancak kullanıcıya ne zaman onay istemi gönderileceğine karar vermek için kullanılabilir.

Başlık dizesiyle birlikte aşağıdaki boole ipuçları şu şekilde tanımlanır:

  • readOnlyHint: Doğru ise araç, ortamını değiştirmez. Varsayılan: false.
  • destructiveHint: Doğru ise araç, yıkıcı işlemler gerçekleştirebilir. Yanlış ise araç yalnızca ekleme işlemleri gerçekleştirebilir. Varsayılan: true.
  • idempotentHint: Doğru ise aracın aynı bağımsız değişkenlerle tekrar tekrar çağrılması, ortamı üzerinde ek bir etki yaratmaz. Varsayılan: false.
  • openWorldHint: Doğru ise araç, harici varlıkların "açık dünyası" ile etkileşim kurabilir. Yanlış ise araç yalnızca dahili varlıklarla etkileşim kurabilir. Örneğin, web arama aracı açık dünya olurken bellek aracı açık dünya olmaz.

Yıkıcı İpucu: ❌ | Aynı Sonucu Veren İpucu: ❌ | Salt Okunur İpucu: ✅ | Açık Dünya İpucu: ❌