MCP Tools Reference: mapstools.googleapis.com

Araç: resolve_names

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

Giriş Koşulları (ÇOK ÖNEMLİ):

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

    • Her sorgu nesnesi şunları içermelidir:
      • 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 (object - İSTEĞE BAĞLI): Belirli bir coğrafi bölgenin yakınındaki sonuçlara öncelik vermek için kullanılır.

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

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

Instructions for Tool Call:

  • Belirginlik (CRITICAL): 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 aşağı akış araçları, ham adres veya yer adı dizelerini doğrudan kabul ediyorsa bu aracı ÇAĞIRMAYIN.

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

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

Aşağıdaki örnekte, resolve_names MCP aracını çağırmak için curl'nın 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 tool's MCP 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ülecek konum sorgularının listesi. En fazla 20 sorgu belirtebilirsiniz.
locationBias

object (LocationBias)

İsteğe bağlı. Çözünürlük sonuçlarını etkilemek için isteğe bağlı bir bölge. Belirtilmesi halinde, çözüm sonuçları bu bölgeye daha yakın olan öğelerden yana olacaktır. location_bias veya region_code eklemek, arama alanını daraltarak genellikle daha iyi sonuçlar sağlar.

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

string

İsteğe bağlı. Çözümleme sonuçlarını etkilemek için isteğe bağlı bir bölge kodu. Belirtilmişse çözüm sonuçları, belirtilen bölgede veya bölgenin yakınında bulunan öğelerden yana olacaktır. Bu, bir CLDR bölge kodu olmalıdır. Örneğin, "US" veya "CA". location_bias veya region_code eklemek, arama alanını daraltarak genellikle daha iyi sonuçlar sağlar.

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

LocationQuery

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

string

Zorunlu. Google Haritalar'da belirli bir coğrafi konum öğesine (ö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 "Eiffel Tower, Paris". Sorgular belirli bir adres veya yer adı olmalıdır. Zincir adı (ör. Starbucks) gibi genel 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 önyargısının türü. type aşağıdakilerden yalnızca biri olabilir:
viewport

object (Viewport)

Sınırlayıcı kutuyla tanımlanan bir 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 en 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

Enlem değeri derece cinsinden olmalıdır. [-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)
    },
    ...
  }
}
Alanlar
results[]

object (Result)

Yalnızca çıkış. Konum sorgularından elde edilen çözümlenmiş öğelerin listesi. İsteğin queries dizinleriyle 1:1 eşleneceği garanti edilir. i dizinindeki boş dize, bu sorgu için çözümlemenin başarısız olduğunu gösterir. Çözüm başarısız olursa 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 harita. Anahtar, queries alanındaki başarısız isteğin dizinidir. Değer, çözümün neden başarısız olduğunu ayrıntılı olarak açıklayan hata durumudur.

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

Sonuç

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

object (Entity)

Yalnızca çıkış. Konum sorgusundan elde edilen çözümlenmiş öğe.
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 önek 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, türün tam nitelikli adı olmalıdır. Bu ad, kanonik biçimde ve başında nokta olmadan yazılmalıdır. İstemcilerin bunlarla iletişime geçmeye çalışmaması için bu URI referanslarına şema yazmayın.

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

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

Any'nın orijinal tasarımında, bu tür URL'lerde bir tür çözümleme hizmeti başlatma olasılığı değerlendirilmiş ancak Protobuf hiçbir zaman böyle bir hizmet uygulamamış ve bu URL'lerle iletişime geçmenin sorunlu ve olası bir güvenlik sorunu olduğunu düşünmüştür. Tür URL'lerine ulaşmaya çalışmayın.
value

string (bytes format)

type_url tarafından açıklanan türün Protobuf serileştirilmiş halini 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 güven düzeyi, çözümün büyük olasılıkla doğru olduğunu ancak başka adayların da olabileceğini gösterir.
HIGH Yüksek güven düzeyi, çözünürlüğün doğru olduğunu ve belirli bir coğrafi alanı temsil ettiğini (ör. belirli bir yer) gösterir.

Araç Ek Açıklamaları

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