Maps Tools Resolution API

Maps Tools Resolution API, Haritalar deneyimi ajan araçları'nın (eski adıyla Maps Grounding Lite) bir parçasıdır. Konum adlarını ve Google Haritalar URL'lerini Google Haritalar yer kimliklerine dönüştüren toplu uç noktalar sağlar. Döndürülen yer kimliklerini diğer Google Haritalar Platformu API'leriyle kullanabilirsiniz. Her yanıtta, çözümlenen yerleri Google Haritalar'da liste olarak kaydeden bir bağlantı da bulunur.

Resolution API, hem REST yöntemleri hem de Haritalar deneyimi ajan araçları MCP sunucusundaki araçlar olarak kullanılabilir:

Başlamadan önce

Resolution API'yi kullanmak için faturalandırmanın ve Maps Experience Agent Tools API hizmetinin etkinleştirildiği bir Google Cloud projeniz olmalıdır. Talimatlar için Google Cloud projenizde Haritalar deneyimi temsilci araçlarını etkinleştirme başlıklı makaleyi inceleyin.

API erişimi ve kimlik doğrulama

Resolution API, hem API anahtarını hem de OAuth 2.0 kimlik bilgilerini destekler.

API anahtarı

X-Goog-Api-Key başlığında geçerli bir Google Haritalar Platformu API anahtarı ileterek veya bu anahtarı istek URL'sine ekleyerek isteklerin kimliğini doğrulayabilirsiniz:

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

Bu sayfadaki örneklerde API_KEY kısmını API anahtarınızla değiştirin.

OAuth 2.0 kapsamları

OAuth yetkilendirmesi kullanıyorsanız aşağıdaki kapsam desteklenir:

• https://www.googleapis.com/auth/maps-platform.mapstools

Kullanım sınırları

Resolution API için aşağıdaki varsayılan kotalar geçerlidir:

• ResolveNames: Her proje için dakikada 600 sorgu.
• ResolveMapsUrls: Her proje için dakikada 600 sorgu.
• Grup boyutu: Her istekte en fazla 20 sorgu veya URL.

Her istek, içerdiği öğe sayısına bakılmaksızın bir sorgu olarak sayılır.

Fiyatlandırma

ResolveNames ve ResolveMapsUrls istekleri, Places API Text Search Essentials (IDs Only) SKU'su kapsamında ücretsiz (0 ABD doları) olarak faturalandırılır. Diğer Maps Experiments temsilci araçlarında olduğu gibi, projenizin bir faturalandırma hesabı olmalıdır.

İstek doğrulama ve kısıtlamalar

Aşırı yükü önlemek ve hızlı yanıt süreleri sağlamak için toplu istekler aşağıdaki kurallara göre doğrulanır:

• Grup boyutu sınırı: Her iki yöntem de her istekte en fazla 20 öğeye izin verir.
• ResolveNames koşulları:
  • queries içindeki her öğe, boş olmayan bir text parametresi belirtmelidir.
  • Sorgular, "Googleplex, Mountain View, CA" veya "Eiffel Tower, Paris" gibi belirli bir yer adını ya da adresi temsil etmelidir.
  • "restaurants in New York" gibi genel kategori aramaları veya "Starbucks" gibi konum içermeyen genel zincir adları desteklenmez ve çözümlenemeyebilir.
• ResolveMapsUrls koşulları:
  • Her URL, yapısal olarak geçerli bir Google Haritalar URL'si olmalıdır.
  • Desteklenen biçimler şunlardır:
    • Standart yer URL'si: https://www.google.com/maps/place/...
    • Kısaltılmış URL: https://maps.app.goo.gl/...
  • https://maps.google.com/?q=restaurant gibi genel sorgu tabanlı Haritalar URL'leri ve tek bir benzersiz yeri işaret etmeyen URL'ler desteklenmez.

Çözümlenen yerleri Google Haritalar'a kaydetme

Bir gruptaki en az bir öğe çözümlenirse yanıt bir saveToMapsUrl alanı içerir. Bu, gruptaki başarıyla çözümlenen tüm yerleri içeren tek bir Google Haritalar bağlantısıdır. Bu bağlantıyı, çözümlenen yerleri Google Haritalar'da liste olarak kaydetmek, paylaşmak veya açmak isteyen kullanıcılara sunun.

Her zaman API tarafından döndürülen bağlantıyı kullanın. Bağlantıyı kendiniz oluşturmayın. Gruptaki hiçbir öğe çözümlenmezse yanıt saveToMapsUrl içermez.

Kısmi hataları işleme

Her iki yöntem de toplu işlemcidir. Bir gruptaki bazı öğeler çözümlenemezse genel istek, üst düzey bir hatayla başarısız olmaz. Bunun yerine API, kısmi başarı yanıtı döndürür ve yanıtı öğe bazında hatalar için kontrol etmeniz gerekir.

Yanıtı yorumlama

1. Garantili 1:1 eşleşme: Döndürülen results listesi (ResolveNames için) veya entities listesi (ResolveMapsUrls için), dizine göre giriş listesiyle 1:1 eşleşir.
2. Başarısızlıklar için boş öğeler: i dizinindeki öğe çözümlenemezse sonuç listesinde i dizininde boş bir nesne ({}) bulunur.
3. failedRequests haritası: Yanıtta bir failedRequests haritası bulunur.
   • Anahtar, başarısız öğenin 0 tabanlı dizinidir (JSON'da dize olarak temsil edilir).
   • Değer, hata kodunu ve öğenin neden başarısız olduğunu açıklayan bir mesajı içeren bir google.rpc.Status nesnesidir.
4. saveToMapsUrl yalnızca başarılı olanları kapsar: saveToMapsUrl bağlantısı yalnızca çözüme ulaştırılan öğeleri içerir. Başarısız olan öğeler dahil edilmez.

Bir öğe başarısız olduğu için tüm toplu işlemin başarısız olduğunu varsaymayın. Çözülemeyen öğeler olup olmadığını öğrenmek için her zaman failedRequests sayfasını kontrol edin.

Öğe başına hatalar

Aşağıdaki tabloda, failedRequests içinde görebileceğiniz öğe bazlı hatalar listelenmiştir:

Yalnızca INTERNAL ile başarısız olan öğeleri yeniden deneyin.

Üst düzey hatalar

API, aşağıdaki durumlarda kısmi yanıt yerine üst düzey bir hata döndürür:

• Geçersiz istek (400 INVALID_ARGUMENT): İstek 20'den fazla öğe içeriyor, bir ResolveNames isteğinde sorgu yok veya boş bir text değeri olan bir sorgu var ya da bir ResolveMapsUrls isteğinde boş olan veya söz dizimi açısından geçerli bir URL olmayan bir URL var. Tek bir geçersiz öğe, tüm isteğin başarısız olmasına neden olur.
• Kimlik doğrulama, izin veya kota hataları: Örneğin, API anahtarı eksik veya geçersiz ya da istek kullanım sınırlarını aşıyor.
• Sunucu hataları (500 INTERNAL): İsteği yeniden deneyin.

MCP ile Resolution API'yi kullanma

https://mapstools.googleapis.com/mcp adresindeki Maps Experiments ajan araçları MCP sunucusu, Resolution API'yi iki araç olarak sunar:

• resolve_names: Bir grup konum adını veya adresini yer kimliklerine dönüştürür.
• resolve_maps_urls: Bir grup Google Haritalar URL'sini yer kimliklerine dönüştürür.

LLM'nizi MCP sunucusunu kullanacak şekilde yapılandırdığınızda bu araçlar, diğer Haritalar deneyimi temsilci araçlarıyla birlikte kullanılabilir. Araçlar, REST yöntemleriyle aynı girişleri kabul eder, aynı kısıtlamaları uygular ve aynı kısmi hata yanıtını döndürür.

Aracın yanıtları save_to_maps_url alanını içerir. Araç açıklamaları, LLM'ye kullanıcı çözümlenen yerleri Google Haritalar'da liste olarak kaydetmek, paylaşmak veya açmak istediğinde bağlantıyı kendisi oluşturmak yerine bu bağlantıyı sunmasını söyler.

Aşağıdaki örnekte, resolve_names aracını doğrudan çağırmak için curl kullanılmaktadır:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

resolve_maps_urls yöntemini çağırmak için name değerini resolve_maps_urls olarak ayarlayın ve arguments içinde bir urls dizisi iletin.

REST API spesifikasyonu ve curl örnekleri

ResolveNames

Yöntem: POST

https://mapstools.googleapis.com/v1:resolveNames

İstek gövdesi biçimi

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}

• queries (Zorunlu): Çözümlenecek sorguların tekrarlanan listesi (en fazla 20).
• locationBias (İsteğe bağlı): Sonuçları yerel bir bölgeye yönlendirmek için görüntü alanı sınırlayıcı kutusu.
• regionCode (İsteğe bağlı): Sonuçları etkilemek için CLDR ülke kodu (ör. "US" veya "FR").

Curl örneği: Başarılı çözüm

Bu sorgu "Googleplex" ve "Eyfel Kulesi"ni çözümler.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"

JSON yanıtı

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

Curl örneği: Karışık sonuçlar (kısmi hata)

Bu örnekte, ilk öğe çözümlenemeyen bir metindir ve ikinci öğe geçerli bir yerdir.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"

JSON yanıtı

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

Yöntem: POST

https://mapstools.googleapis.com/v1:resolveMapsUrls

İstek gövdesi biçimi

{
  "urls": [
    "string"
  ]
}

• urls (Zorunlu): Çözümlenecek Google Haritalar URL dizesi listesi (en fazla 20).

Curl örneği: Başarılı çözüm

Aşağıdaki örnekte standart bir Google Haritalar yer URL'si çözümlenmektedir:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON yanıtı

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Curl örneği: Karışık sonuçlar (kısmi hata)

Aşağıdaki örnekte, geçerli bir yer URL'si ve bir yere çözümlenemeyen bir URL çözümlenmektedir:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON yanıtı

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Curl örneği: Doğrulama hatası

Aşağıdaki örnekte, tek bir istekte 20'den fazla URL iletilmektedir:

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON yanıtı

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

Geri bildirim gönder

Resolution API ile ilgili sorun bildirmek veya geri bildirim paylaşmak için Haritalar deneyimi temsilci araçları herkese açık Issue Tracker bileşenini kullanın:

• Hata bildirme
• Özellik isteği gönderme
• Geri bildirim gönderin