MCP Reference: mapstools.googleapis.com

Kullanıcı yer, işletme, adres, konum, önemli yer veya Google Haritalar ile ilgili başka bir arama yapmak istediğinde bu aracı çağırın.

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

1. text_query (dize - ZORUNLU): Birincil arama sorgusu. Bu, kullanıcının ne aradığını net bir şekilde tanımlamalıdır.

   • Örnekler: 'restaurants in New York', 'coffee shops near Golden Gate Park', 'SF MoMA', '1600 Amphitheatre Pkwy, Mountain View, CA, USA', 'pets friendly parks in Manhattan, New York', 'date night restaurants in Chicago', 'accessible public libraries in Los Angeles'.
   • Belirli yer ayrıntıları için: İstenen özelliği (ör. 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address') ekleyin.

2. location_bias (nesne - İSTEĞE BAĞLI): Belirli bir coğrafi bölgenin yakınındaki sonuçlara öncelik vermek için bunu kullanın.

   • Biçim: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
   • Kullanım:
     • 5 km'lik bir yarıçapa yönlendirmek için: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
     • Merkez noktaya güçlü bir şekilde yönlendirmek için: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (radius_meters hariç).

3. language_code (dize - İSTEĞE BAĞLI): Arama sonuçları özetinin gösterileceği dil.

   • Biçim: İki harfli bir dil kodu (ISO 639-1) ve isteğe bağlı olarak ardından bir alt çizgi ve iki harfli bir ülke kodu (ISO 3166-1 alfa-2) gelir (ör. en, ja, en_US, zh_CN, es_MX). Dil kodu sağlanmazsa sonuçlar İngilizce olur.

4. region_code (dize - İSTEĞE BAĞLI): Kullanıcının Unicode CLDR bölge kodu. Bu parametre, varsa bölgeye özgü yer adı gibi yer ayrıntılarını görüntülemek için kullanılır. Parametre, geçerli yasaya göre sonuçları etkileyebilir.

   • Biçim: İki harfli ülke kodu (ISO 3166-1 alfa-2), ör. US, CA.

5. page_size (tam sayı - İSTEĞE BAĞLI): Döndürülecek maksimum yer sayısı (1 ile 10 arasında). Varsayılan değer 5'dir. Yalnızca kullanıcı 5'ten fazla yeri karşılaştırmak istediğinde 5 değerinin üzerine ayarlayın. 6 ile 10 arasındaki değerler daha yüksek maliyet ve daha yüksek gecikmeye neden olur.

6. include_extended_details (Boole - İSTEĞE BAĞLI): Kullanıcı isteği zengin niteliksel analizler, gerçek zamanlı dinamikler veya özel varlık özellikleri gerektirdiğinde bu alanı true olarak ayarlayın. Varsayılan değer false'dir. Bu ayarın true olarak belirlenmesi daha yüksek maliyet ve gecikmeye neden olur.

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

• Konum Bilgisi (KRİTİK): Aramada yeterli konum bilgisi bulunmalıdır. Konum belirsizse (ör. yalnızca "pizzacılar") text_query parametresinde konumu belirtmeniz (ör. "New York'taki pizzacılar") veya location_bias parametresini kullanmanız gerekir. Anlam belirsizliğini gidermek için gerekirse şehir, eyalet/il ve bölge/ülke adını ekleyin.

• Her zaman mümkün olan en spesifik ve bağlam açısından en zengin text_query sağlayın.

• location_bias aracını yalnızca koordinatlar açıkça belirtilmişse veya kullanıcının bilinen bağlamından konum çıkarımı yapmak uygunsa ve daha iyi sonuçlar için gerekliyse kullanın.

• Temellendirilmiş çıkış, mümkün olduğunda attribution alanındaki bilgiler kullanılarak kaynağa atfedilmelidir.

Başlangıç ve varış noktası arasında (isteğe bağlı olarak ara duraklar üzerinden) seyahat rotalarını hesaplar. Her rotanın mesafesini ve süresini döndürür.

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

1. origin ve destination (nesneler - ZORUNLU): Her biri, aşağıdakilerden tam olarak biri kullanılarak sağlanmalıdır:

   • address (dize, ör. 'Eiffel Tower, Paris'). Adlandırılmış yerler, önemli noktalar ve işletmeler doğrudan çözümlenir. Bu nedenle, yalnızca bir ara noktanın coğrafi kodunu almak için önce search_places yöntemini çağırmayın. Kullanıcının bahsettiği şehir, bölge veya ülkeleri ekleyin.
   • lat_lng (nesne, {"latitude": number, "longitude": number}).
   • place_id (dize, ör. 'ChIJOwE_Id1w5EAR4Q27FkL6T_0'), örneğin search_places.

2. intermediate_waypoints (nesne dizisi - İSTEĞE BAĞLI): Başlangıç ve varış noktası arasında sırayla geçilecek en fazla 25 durak. origin ile aynı biçim. TRANSIT ile desteklenmez. Yalnızca kullanıcının istediği durakları ekleyin. 10'dan fazla ara nokta belirtmek daha yüksek maliyete ve daha yüksek gecikmeye neden olur.

3. travel_mode (enum - İSTEĞE BAĞLI): DRIVE (varsayılan), WALK, BICYCLE veya TRANSIT.

4. Zamanlama (İSTEĞE BAĞLI - en fazla BİR tane ayarlayın): UTC farkı içeren RFC 3339 zaman damgaları (ör. '2026-09-19T08:00:00-07:00'). Varsayılan olarak "Şimdi hareket et" seçeneği kullanılır. TRANSIT için zaman, geçmişte en fazla 7 gün veya gelecekte en fazla 100 gün olabilir. Diğer modlarda ise zaman, gelecekte 365 güne kadar olabilir ve geçmişte olmamalıdır.

   • departure_time: Kullanıcı ne zaman ayrılacağını söylediğinde (ör. "yarın sabah 8'de") kullanın.
   • arrival_time: Kullanıcı ne zaman varması gerektiğini söylediğinde (ör. "saat 09:00'da orada ol") kullanın.

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

   • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (varsayılan): Canlı trafik, olaylar ve kapalı yollar dikkate alınmaz. 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ış TVS hakkında soru sorduğunda ayarlayın. Daha yüksek maliyet ve gecikmeye neden olur.

6. location_bias (nesne - İSTEĞE BAĞLI): Ara nokta adreslerindeki yer adlarının anlam belirsizliğini gidermek için kullanılan {"latitude": number, "longitude": number}. Ad belirsizse (ör. "Springfield") ve kullanıcı bölge belirtmediyse adı address alanında verildiği gibi bırakın ve bölgeyi tahmin etmek yerine location_bias alanını amaçlanan bölgeye ayarlayın.

7. compute_alternative_routes (boole - İSTEĞE BAĞLI): Yalnızca kullanıcı rota seçenekleri veya alternatifleri istediğinde true olarak ayarlayın. Varsayılan değer false olup yalnızca önerilen rotayı döndürür.

8. include_polyline (Boole - İSTEĞE BAĞLI): Yalnızca rota geometrisi (encoded_polyline) gerektiğinde true olarak ayarlayın. Varsayılan değer false'dir.

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

• Başlangıç veya hedef eksikse aracı çağırmadan önce kullanıcıdan açıklama istemeniz ZORUNLUDUR.
• "A, B'den ne kadar uzakta?" sorularında B'yi origin, A'yı destination olarak kullanın.

Örnek Araç Çağrısı: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

Yanıtla ilgili talimatlar:

• Alternatif rotalar istendiğinde rotalar en çok önerilenden en az önerilene doğru sıralanır.
• routes boşsa kullanıcıya rota bulunamadığını söyleyin. Rotayı tahmin etmeye çalışmayın.
• DRIVE rotası üzerindeki yerleri bulmak için rotanın retrieval_token değerini search_along_route değerine iletin. Jeton 10 dakika boyunca geçerlidir.
• Yalnızca aracın döndürdüğü gerçekleri belirtin. Adım adım yol tarifleri, toplu taşıma hatları, istasyonlar, peronlar veya aktarmalar uydurmayın.
• Temellendirilmiş çıkış, mümkün olduğunda her rotanın attribution alanı kullanılarak kaynağa atfedilmelidir.

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.

Belirli konum sorgularının (yer işareti adları veya tam adresler) toplu listesini standart Google Haritalar yer kimliklerine dönüştürür.

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

1. queries (nesne dizisi - ZORUNLU): Çözümlenecek konum sorgularının listesi. En fazla 20 sorgu belirtebilirsiniz.

   • Her sorgu nesnesinde şunlar bulunmalıdır:
     • text (dize - ZORUNLU): Çözümlenecek belirli bir yer adını veya adresi temsil eden metin sorgusu.
       • Örnekler: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

2. location_bias (nesne - İSTEĞE BAĞLI): Belirli bir coğrafi bölgenin yakınındaki sonuçlara öncelik vermek için bunu kullanın.

   • Biçim: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

3. region_code (dize - İSTEĞE BAĞLI): Sonuçları etkilemek için kullanıcının Unicode CLDR bölge kodu (iki harfli ülke kodu, ör. US, CA).

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

• Belirginlik (KRİTİK): Sorgular belirli bir yer adını veya adresi temsil etmelidir. 'restaurants' gibi genel aramalar veya 'Starbucks' gibi zincir adları desteklenmez.
• Çağırmayı planladığınız alt araçlar ham adres veya yer adı dizelerini doğrudan kabul ediyorsa bu aracı KULLANMAYIN.

Google Haritalar'a kaydetme:

• Yanıt, başarıyla çözümlenen tüm yerleri içeren tek bir Google Haritalar bağlantısı olan save_to_maps_url alanını içerir.
• Kullanıcı, çözümlenen yerleri Google Haritalar'da liste olarak kaydetmek, paylaşmak veya açmak istediğinde bu bağlantıyı kullanıcıya sunun. Bu bağlantıyı kendiniz OLUŞTURMAYIN.

Hata İşleme (KRİTİK):

• Bu bir toplu işleme aracıdır. Bir istek "karışık sonuçlar" döndürebilir (ör. bazı sorgular başarıyla çözülürken diğerleri başarısız olur).
• results çıkış listesinin, giriş queries dizinleriyle 1:1 eşleşmesi garanti edilir. Başarısız bir sorgu, results listesindeki ilgili dizinde boş bir Result mesajı (entity ayarlanmamış) döndürür.
• Hangi sorgu dizininin başarısız olduğunu belirlemek için yanıttaki failed_requests eşleme alanını kontrol etmeniz GEREKİR. failed_requests anahtarı, istekteki başarısız sorgunun 0 tabanlı dizinini temsil eder. Kısmi bir hata nedeniyle toplu çağrının tamamının başarısız olduğunu varsaymayın.

Google Haritalar URL'lerinin listesini standart Google Haritalar yer kimliklerine dönüştürür.

Bu aracın ne zaman çağrılacağı (ÖNEMLİ):

• Kullanıcı bir veya daha fazla Google Haritalar paylaşım bağlantısı ya da URL'si (ör. "https://maps.app.goo.gl/...") verdiğinde bu aracı kullanın. "https://www.google.com/maps/place/..." veya "https://maps.google.com/...") ve temel standart yer kimliklerini ayıklamanız gerekiyor.
• Tek bir toplu istekte çözümlenecek en fazla 20 URL belirtebilirsiniz.

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

• urls (dize dizisi - ZORUNLU): Çözümlenecek Google Haritalar URL'lerinin listesi. Her URL, geçerli ve tek bir yeri gösteren Google Haritalar URL'si olmalıdır.

Google Haritalar'a kaydetme:

• Yanıt, başarıyla çözümlenen tüm yerleri içeren tek bir Google Haritalar bağlantısı olan save_to_maps_url alanını içerir.
• Kullanıcı, çözümlenen yerleri Google Haritalar'da liste olarak kaydetmek, paylaşmak veya açmak istediğinde (ör. bir görüşmede paylaşılan yerleri toplamak) bu bağlantıyı kullanıcıya gösterin. Bu bağlantıyı kendiniz OLUŞTURMAYIN.

Hata İşleme (KRİTİK):

• Bu bir toplu işleme aracıdır. Bir istek "karışık sonuçlar" döndürebilir (ör. bazı URL'ler başarıyla çözümlenirken diğerleri başarısız olur).
• entities çıkış listesinin, giriş urls dizinleriyle 1:1 eşleşmesi garanti edilir. Başarısız bir URL çözümlemesi, entities listesindeki ilgili dizinde boş bir Entity mesajı (hiçbir alan ayarlanmamış) ile sonuçlanır.
• Hangi URL dizininin başarısız olduğunu belirlemek için yanıttaki failed_requests eşleme alanını kontrol etmeniz ZORUNLUDUR. failed_requests anahtarı, istekteki başarısız URL'nin 0 tabanlı dizinini temsil eder. Kısmi bir hata nedeniyle toplu çağrının tamamının başarısız olduğunu varsaymayın.