MCP Tools Reference: mapstools.googleapis.com

Araç: resolve_names

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

  • Özgüllük (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 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ı 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.

Aşağıdaki kod örneğinde, resolve_names 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": "resolve_names",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Giriş şeması

ResolveNames için istek mesajı.

ResolveNamesRequest

JSON gösterimi 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Alanlar
queries[]

object (LocationQuery)

Zorunlu. Çözümlenecek konum sorgularının listesi. En fazla 20 sorgu belirtebilirsiniz.
locationBias

object (LocationBias)

İsteğe bağlıdır. Çözünürlük sonuçlarını etkileyecek isteğe bağlı bir bölge. Belirtilirse çözümleme sonuçları bu bölgeye daha yakın olan varlıklara göre önceliklendirilir. location_bias veya region_code ifadesini eklemek, arama alanını daraltarak genellikle daha iyi sonuçlar verir.

Hem location_bias hem de region_code belirtilirse location_bias, region_code'e göre öncelikli olur.
regionCode

string

İsteğe bağlıdır. Çözümleme sonuçlarını etkilemek için isteğe bağlı bir bölge kodu. Belirtilirse çözümleme sonuçları, belirtilen bölgede veya bölgenin yakınında bulunan öğelere göre belirlenir. Bu, CLDR bölge kodu olmalıdır. Örneğin, "US" veya "CA". location_bias veya region_code ifadesini eklemek, arama alanını daraltarak genellikle daha iyi sonuçlar verir.

Hem location_bias hem de region_code belirtilirse location_bias, region_code'e göre öncelikli olur.

LocationQuery

JSON gösterimi 
{
  "text": string
}
Alanlar
text

string

Zorunlu. Google Haritalar'da belirli bir coğrafi öğeye (ör. yer veya adres) çözümlenecek metin sorgusu. Sorgu ne kadar ayrıntılı olursa çözüm de o kadar doğru olur. Örneğin, "San Francisco", "Googleplex, Mountain View, CA", "1600 Amphitheatre Parkway, Mountain View, CA" veya "Eyfel Kulesi, Paris". Sorgular belirli bir adres veya yer adı olmalıdır. Zincir adı (ör. Starbucks) gibi yaklaşık konumlar veya "restoranlar" gibi arama sorguları desteklenmez.

LocationBias

JSON gösterimi 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Alanlar
type birleşik alanı. Konum tercihi türü. type aşağıdakilerden yalnızca biri olabilir:
viewport

object (Viewport)

Sınırlayıcı kutu tarafından tanımlanan görüntü alanı.

Görüntü alanı

JSON gösterimi 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Alanlar
low

object (LatLng)

Zorunlu. Görüntü alanının alt noktası.
high

object (LatLng)

Zorunlu. Görüntü alanının en yüksek noktası.

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.

Çıkış şeması

ResolveNames için yanıt mesajı.

ResolveNamesResponse

JSON gösterimi 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
Alanlar
results[]

object (Result)

Yalnızca çıkış. Konum sorgularından çözümlenen varlıkların listesi. İstek queries dizinleriyle 1:1 eşleme garantisi. i dizinindeki boş dize, söz konusu sorgu için çözümlemenin başarısız olduğunu gösterir. Çözüm başarısız olduysa lütfen hata durumu için failed_requests alanını kontrol edin.
failedRequests

map (key: integer, value: object (Status))

Yalnızca çıkış. Kısmi hataları bildiren bir eşleme. Anahtar, queries alanındaki başarısız isteğin dizinidir. Değer, çözümün neden başarısız olduğunu açıklayan hata durumudur.

"key": value çiftlerinin listesini içeren bir nesne. Örnek: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

Yalnızca çıkış. Başarıyla çözümlenen tüm öğeleri Google Haritalar'a kaydetme bağlantısı

Sonuç

JSON gösterimi 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Alanlar
entity

object (Entity)

Yalnızca çıkış. Konum sorgusundan çözümlenen varlık.
confidence

enum (Confidence)

Yalnızca çıkış. Çözümün güven düzeyi.

Varlık

JSON gösterimi 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Alanlar
entity birleşik alanı. Çözümlenen varlık türü. entity aşağıdakilerden yalnızca biri olabilir:
place

string

Çözümlenen yerin kaynak adı.

FailedRequestsEntry

JSON gösterimi 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Alanlar
key

integer
value

object (Status)

Durum

JSON gösterimi 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Alanlar
code

integer

Durum kodu, google.rpc.Code enum değeri olmalıdır.
message

string

Geliştiriciye yönelik hata mesajı (İngilizce olmalıdır). Kullanıcıya gösterilen tüm hata mesajları yerelleştirilmiş olup google.rpc.Status.details alanında gönderilmeli veya istemci tarafından yerelleştirilmelidir.
details[]

object

Hata ayrıntılarını içeren mesajların listesi. API'lerin kullanabileceği ortak bir mesaj türleri kümesi vardır.

Herhangi türde alanlar içeren bir nesne. Ek bir "@type" alanı, türü tanımlayan bir URI içerir. Örnek: { "id": 1234, "@type": "types.example.com/standard/id" }.

Tümü

JSON gösterimi 
{
  "typeUrl": string,
  "value": string
}
Alanlar
typeUrl

string

Serileştirilmiş Protobuf mesajının türünü, eğik çizgiyle biten bir ön ek ve tam nitelikli tür adından oluşan bir URI referansıyla tanımlar.

Örnek: type.googleapis.com/google.protobuf.StringValue

Bu dize en az bir / karakteri içermelidir ve son / karakterinden sonraki içerik, başında nokta olmadan standart biçimdeki türün tam nitelikli adı olmalıdır. İstemcilerin bu URI referanslarıyla iletişim kurmaya çalışmaması için bunlara şema yazmayın.

Önek rastgeledir ve Protobuf uygulamalarının, türü tanımlamak için son / dahil olmak üzere her şeyi kaldırması beklenir. type.googleapis.com/, bazı eski uygulamaların gerektirdiği yaygın bir varsayılan önektir. Bu ön ek, türün kaynağını belirtmez ve bu ön eki içeren URI'lerin herhangi bir isteğe yanıt vermesi beklenmez.

Tüm tür URL dizeleri, referans içeriğinin yalnızca alfanümerik karakterlerden, yüzde kodlu çıkışlardan ve aşağıdaki kümedeki karakterlerden (dış tırnak işaretleri hariç) oluşması gerektiği ek kısıtlamasıyla (metin biçimi için) yasal URI referansları olmalıdır: /-.~_!$&()*+,;=. Yüzde kodlamalarına izin vermemize rağmen, mevcut ayrıştırıcılarla karışıklığı önlemek için uygulamalar bunları kaçış karakteri olarak kullanmamalıdır. Örneğin, type.googleapis.com%2FFoo reddedilmelidir.

Any uygulamasının orijinal tasarımında, bu tür URL'lerde bir tür çözümleme hizmeti başlatma olasılığı değerlendirilmişti ancak Protobuf hiçbir zaman böyle bir hizmet uygulamadı ve bu URL'lerle iletişime geçmenin sorunlu ve potansiyel bir güvenlik sorunu olduğunu düşünüyor. İletişim türü URL'lerini kullanmaya çalışmayın.
value

string (bytes format)

type_url tarafından açıklanan türün Protobuf serileştirmesini içerir.

Base64 kodlu bir dize.

Güven

Çözümün güven düzeyi.

Sıralamalar
CONFIDENCE_UNSPECIFIED Varsayılan değer. Bu değer kullanılmıyor.
MEDIUM Orta düzeyde güven, çözümün muhtemelen doğru olduğunu ancak başka adaylar da olabileceğini gösterir.
HIGH Yüksek güven, çözümün doğru olduğunu ve belirli bir coğrafi öğeyi (ör. belirli bir yer) temsil ettiğini gösterir.

Araç Notları

Araç notları, belirli bir aracın temel riskini açıklamak için MCP istemcilerine gönderilir. Çoğu istemci bu ipuçlarını güvenilir olmayan olarak değerlendirir 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şime girebilir. Yanlış ise araç yalnızca dahili varlıklarla etkileşim kurabilir. Örneğin, web arama aracı açık dünya iken bellek aracı açık dünya değildir.

Yıkıcı İpucu: ❌ | Eşgüçlü İpucu: ❌ | Salt Okunur İpucu: ✅ | Açık Dünya İpucu: ❌