Rota boyunca arayın

search_along_route aracı, LLM'nin doğal dildeki bir sorgudan seyahat rotası üzerindeki yerleri bulmasını sağlar. Örneğin, Lake Tahoe'ya giderken elektrikli araç şarj istasyonları veya San Francisco ile San Jose arasındaki kafeler. Araç, eşleşen yerlerin ve yol uzatma ödünlerinin yapay zeka tarafından üretilmiş bir özetini döndürür. Özette belirtilen her yer için yanıtta yer kimliği, enlem/boylam koordinatları, Google Haritalar bağlantıları, gerekli atıf ve rota değişikliği metrikleri de yer alır.

Her search_along_route isteği bir Pro seçeneğidir ve Maps Grounding Pro SKU kapsamında faturalandırılır.

search_along_route aracını MCP sunucusu üzerinden veya searchAlongRoute REST yöntemi olarak çağırabilirsiniz. Bu sayfada istek seçenekleri, rota belirtme, yanıtın içeriği ve isteklerin nasıl faturalandırıldığı açıklanmaktadır. Şemaların tamamı için search_along_route MCP referansına ve searchAlongRoute REST referansına bakın.

İstek seçenekleri

LLM, aracı çağırırken kullanıcının isteğine ve aracın açıklamasına göre bu seçenekleri ayarlar. Kendi talimatlarınızla modelin hangi seçenekleri kullanacağını etkileyebilirsiniz. Pro kullanımını kontrol etme başlıklı makaleyi inceleyin.

Aşağıdaki tabloda search_along_route için istek seçenekleri açıklanmaktadır:

Seçenek Açıklama
text_query Zorunlu. Rota üzerindeki yerler için doğal dilde arama sorgusu (ör. ev chargers, coffee veya vegetarian restaurants).
retrieval_token, route_endpoints veya encoded_polyline Zorunlu. Arama yapılacak rota. Her istekte bu üç alandan birini belirtin. Rota belirtme başlıklı makaleyi inceleyin.
travel_mode İsteğe bağlıdır. Rotayı ve sapmaları hesaplamak için kullanılan ulaşım modu: DRIVE (varsayılan), WALK veya BICYCLE. WALK ve BICYCLE yalnızca route_endpoints ile desteklenir. TRANSIT desteklenmiyor. 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 yaya rotaları için kullanıcıya bu uyarıyı göstermeniz gerekir.
routing_preference İsteğe bağlıdır. Trafik verilerinin rota ve sapma sürelerini hesaplamak için nasıl kullanılacağı: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (varsayılan) veya ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, mümkün olduğunda canlı trafik koşullarını kullanır ve WALK veya BICYCLE için desteklenmez.
include_extended_details İsteğe bağlıdır. true olduğunda özet, yorumlardan elde edilen analizler, menü öğeleri, atmosfer, ziyaretçi ipuçları, EV şarj ünitesi kullanılabilirliği veya benzin fiyatları gibi kapsamlı yer ayrıntılarını içerir. Varsayılan değer false'dir.
language_code İsteğe bağlıdır. Özet ve yerelleştirilmiş rota dışı mesafe için BCP-47 dil kodu (ör. en-US veya ja). Varsayılan değer en-US'dir.
region_code İsteğe bağlıdır. Kullanıcının iki harfli CLDR bölge kodu (ör. US veya CA). Bölgeye özgü yer adlarını etkiler ve geçerli yasaya göre sonuçları etkileyebilir.

Rota belirtme

Her search_along_route isteği, birbirini hariç tutan üç alandan birini kullanarak rotayı belirtmelidir. Birden fazla rota alanı ayarlamak veya üçünü de atlamak INVALID_ARGUMENT hatası döndürür.

Aşağıdaki tabloda, rota belirtmenin üç yolu karşılaştırılmaktadır:

Rota seçeneği Giriş biçimi Desteklenen seyahat modları detourDuration iade Ne zaman kullanılır?
retrieval_token Önceki bir compute_routes yanıtından gelen retrievalToken dizesi (10 dakika boyunca geçerlidir) DRIVE Evet Temsilci, ara durakları olan rotalar da dahil olmak üzere bir sürüş rotası için compute_routes yöntemini zaten çağırmış ve kullanıcı bu rota üzerindeki yerleri sormuş.
route_endpoints origin ve destination yol noktaları (address, place_id veya lat_lng) içeren bir nesne DRIVE, WALK ve BICYCLE Evet Kullanıcı, önce compute_routes aracını çağırmadan tek bir adımda iki konum arasındaki yerleri bulmak istiyor veya rota, yürüyüş ya da bisiklet kullanıyor.
encoded_polyline Sürüş rotasını temsil eden kodlanmış çoklu çizgi dizesi DRIVE Hayır (yalnızca localizedDetourDistance döndürür) Uygulamanızda, Routes API gibi başka bir kaynaktan alınan bir rota çoklu çizgisi zaten varsa.

Zincir compute_routes ve search_along_route

Bir compute_routes isteği DRIVE seyahat modunu kullandığında yanıttaki her rota bir retrievalToken alanı içerir. Bu jeton 10 dakika boyunca geçerlidir ve ara duraklar da dahil olmak üzere hesaplanan rotayı kodlar. Kullanıcı, bu rota üzerindeki yerleri sorarak devam ettiğinde LLM, retrievalToken değerini search_along_route içinde retrieval_token olarak iletebilir.

Genişletilmiş yer ayrıntıları

Kullanıcının isteği, rota boyunca niteliksel analizler, gerçek zamanlı koşullar veya özel özellikler gerektirdiğinde include_extended_details değerini true olarak ayarlayın. Örneğin:

  • Yorumcuların söyledikleri: Yorumlara dayalı analizler, müşteri yaklaşımı ve geri bildirimler.
  • Özel teklifler: Menü öğeleri, yemekler, özel yemekler, içecekler veya işletmeyle ilgili öne çıkanlar.
  • Atmosfer: iç dekor, estetik, ambiyans veya ruh hali.
  • Ziyaretçiler için pratik ipuçları ve gerçek zamanlı veriler: önceden rezervasyon yapılması gerekip gerekmediği, bekleme süreleri, yerin ne kadar yoğun olduğu, elektrikli araç şarj cihazı kullanılabilirliği, benzin fiyatları, otopark ve tesisler.

Rota boyunca standart aramalar (ör. konuma, çalışma saatlerine ve rota dışına çıkma süresine göre benzin istasyonları, dinlenme tesisleri veya kafeler bulma) için include_extended_details değerini false (varsayılan) olarak bırakın. Genişletilmiş ayrıntılar içeren isteklerin tamamlanması daha uzun sürer ancak her search_along_route isteği Pro SKU kapsamında faturalandırıldığından ek ücret alınmaz.

Örnekler

Aşağıdaki MCP isteği, route_endpoints ve trafiğe duyarlı rotayı kullanarak San Francisco ile Tahoe Gölü arasındaki elektrikli araç şarj istasyonlarını arar:

{
  "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
}

Aşağıdaki örnekte, önceki bir compute_routes yanıtından alınan retrieval_token kullanılmaktadır:

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

RETRIEVAL_TOKEN değerini, compute_routes tarafından döndürülen retrievalToken dizesiyle değiştirin.

Aşağıdaki örnekte, ilk istek searchAlongRoute REST yöntemine gönderilmektedir:

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"

API_KEY kısmını API anahtarınızla değiştirin.

Yanıt

Yanıtta aşağıdaki alanlar bulunur:

  • summary: Arama sonuçlarının ve sapma ödünleşimlerinin doğal dilde özeti. results içindeki girişlerle eşlenen [0] gibi sıfır tabanlı alıntılar içerebilir.
  • results[]: Özetlenen yerlerin sıralı listesi. Her giriş şunları içerir:
    • place: Yerle ilgili ayrıntılar:
      • place: Yerin kaynak adı. places/{id} biçimindedir.
      • id: Yer kimliği. Bu kimliği, yeri haritada göstermek gibi işlemler için diğer Google Haritalar Platformu API'leriyle birlikte kullanabilirsiniz.
      • location: Yerin enlem/boylam koordinatları.
      • googleMapsLinks: Yer (placeUrl), yol tarifi (directionsUrl), yorumlar (reviewsUrl), fotoğraflar (photosUrl) ve yorum yazma (writeAReviewUrl) için Google Haritalar bağlantıları.
      • attribution: Yerle birlikte göstermeniz gereken atıf. İlişkilendirme koşulları bölümünü inceleyin.
    • detourSummary: Rota üzerindeki bu yerde durmak için gereken ek seyahat süresi ve mesafe:
      • localizedDetourDistance: İstek dilinde biçimlendirilmiş ek mesafe (ör. "1.2 mi" veya "1.9 km").
      • detourDuration: Ek seyahat süresi, süre dizesi olarak (ör. "180s"). Rota encoded_polyline ile belirtildiğinde bu alan ayarlanmaz.
  • contentToken: Yanıttaki yerleri ek ücret ödemeden Places UI Kit ile görüntülemenize olanak tanıyan temsilci veri görselleştirme jetonu (Önizleme). Yanıt en az bir yer içerdiğinde döndürülür.

Alanlarla ilgili tüm ayrıntılar için search_along_route referansına bakın.

Faturalandırma ve kotalar

Her search_along_route isteği, Maps Grounding Pro SKU'su kapsamında faturalandırılabilir bir etkinliktir. include_extended_details ayarını true veya routing_preference ayarını ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL olarak belirlemek ek ücret alınmasına neden olmaz. Temsilciniz önce compute_routes aracını çağırıp ardından retrieval_token aracını search_along_route aracına iletirse her araç çağrısı ayrı bir istek olarak faturalandırılır.

Places UI Kit ile bir search_along_route yanıtındaki yerleri gösteriyorsanız temsilci veri görselleştirme jetonunu (Önizleme) kullanarak bu Places UI Kit isteklerinin faturalandırılmamasını sağlayabilirsiniz.

search_along_route kotası, her proje için dakikada 300 sorgudur. Fiyatlandırma için Ana fiyatlandırma tablosu ve Hindistan fiyatlandırma tablosu'na bakın.