Maps Tools Resolution API

Maps Tools Resolution API, Maps Grounding Lite'ın 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 birlikte kullanabilirsiniz. Her yanıtta, çözülen yerleri Google Haritalar'da liste olarak kaydeden bir bağlantı da bulunur.

Resolution API, hem REST yöntemleri hem de Maps Grounding Lite MCP sunucusundaki araçlar olarak kullanılabilir:

Başlamadan önce

Resolution API'yi kullanmak için faturalandırmanın etkin olduğu bir Google Cloud projeniz ve Maps Grounding Lite API hizmetinin etkin olması gerekir. Talimatlar için Google Cloud projenizde Maps Grounding Lite hizmetini etkinleştirme başlıklı makaleyi inceleyin.

API erişimi ve kimlik doğrulama

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

API anahtarı

İstekleri, X-Goog-Api-Key üstbilgisinde geçerli bir Google Haritalar Platformu API anahtarı ileterek veya istek URL'sine ekleyerek 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ı

Çözüm API'si için aşağıdaki varsayılan kotalar geçerlidir:

• ResolveNames: Proje başına dakikada 600 sorgu.
• ResolveMapsUrls: Proje başına dakikada 600 sorgu.
• Grup boyutu: İstek başına en fazla 20 sorgu veya URL.

İçerdiği öğe sayısından bağımsız olarak her istek bir sorgu olarak sayılır.

Fiyatlandırma

ResolveNames ve ResolveMapsUrls istekleri, Places API Text Search Essentials (Yalnızca Kimlikler) SKU'su kapsamında ücretsiz ($0) olarak faturalandırılır. Maps Grounding Lite'ın geri kalanında olduğu gibi, projenizde de bir faturalandırma hesabı olmalıdır.

Doğrulama isteği ve kısıtlamalar

Aşırı yüklenmeyi önlemek ve hızlı yanıt süreleri sağlamak için toplu istekler sıkı bir şekilde doğrulanır:

• Grup boyutu sınırı: Her iki yöntemde de istek başına en fazla 20 öğeye izin verilir.
• ResolveNames koşulları:
  • queries içindeki her öğe, boş olmayan bir text parametresi belirtmelidir.
  • Sorgular belirli bir yer adını veya adresi (örneğin, "Googleplex, Mountain View, CA" veya "Eyfel Kulesi, Paris") temsil etmelidir.
  • Genel kategorik aramalar (örneğin, "New York'taki restoranlar") veya konum içermeyen genel zincir adları (örneğin, "Starbucks") 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:
    • Standart yer URL'si: https://www.google.com/maps/place/...
    • Kısaltılmış URL: https://maps.app.goo.gl/...
  • Genel sorguya dayalı Haritalar URL'leri (örneğin, https://maps.google.com/?q=restaurant) 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ıtta saveToMapsUrl alanı bulunur. Bu, toplu işlemdeki başarıyla çözümlenen tüm yerleri içeren tek bir Google Haritalar bağlantısıdır. Çözümlenen yerleri Google Haritalar'da liste olarak kaydetmek, paylaşmak veya açmak isteyen kullanıcılara bu bağlantıyı 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ıtta saveToMapsUrl yer almaz.

Kısmi hataları işleme

Her iki yöntem de toplu işlemcidir. Bir toplu işlemdeki 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 öğe bazında hatalar için yanıtı kontrol etmeniz gerekir.

Yanıtı yorumlama

1. 1:1 eşleme garantisi: Döndürülen results listesi (ResolveNames için) veya entities listesi (ResolveMapsUrls için) dizine göre giriş listesiyle 1:1 eşlenir.
2. Hatalar için boş öğeler: i dizinindeki öğe çözümlenemezse sonuç listesi, i dizininde boş bir nesne {} içerir.
3. failedRequests haritası: Yanıtta failedRequests haritası var.
   • Anahtar, başarısız olan öğenin 0 tabanlı dizinidir (JSON'da dize olarak gösterilir).
   • 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ıları kapsar: saveToMapsUrl bağlantısı yalnızca çözülen öğeleri içerir. Başarısız olan öğeler dahil edilmez.

Bir öğe başarısız oldu diye toplu işlemin tamamının başarısız olduğunu varsaymayın. Hangi öğelerin çözülemediğini öğrenmek için her zaman failedRequests simgesini kontrol edin.

Öğe başına hatalar

Aşağıdaki tabloda, failedRequests içinde görebileceğiniz öğe başına 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 en üst düzeyde hata döndürür:

• Geçersiz istek (400 INVALID_ARGUMENT): İstek 20'den fazla öğe içeriyor, ResolveNames isteğinde sorgu yok veya sorgu boş bir text değeri içeriyor ya da ResolveMapsUrls isteğinde boş olan veya söz dizimi açısından geçerli bir URL olmayan bir URL var. Geçersiz bir öğ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.

Çözüm API'sini MCP ile kullanma

https://mapstools.googleapis.com/mcp adresindeki Maps Grounding Lite MCP sunucusu, Resolution API'yi iki araç olarak kullanıma 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 Maps Grounding Lite MCP sunucusunu kullanacak şekilde yapılandırdığınızda bu araçlar, diğer Maps Grounding Lite 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.

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

Aşağıdaki örnekte resolve_names aracı 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 numaralı telefonu aramak 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 metni biçimi

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

• queries (Zorunlu): Çözülecek sorguların tekrarlanan listesi (en fazla 20).
• locationBias (İsteğe bağlı): Sonuçları yerel bir bölgeye yönlendirmek için kullanılan 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 metin, ikinci öğe ise 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 metni biçimi

{
  "urls": [
    "string"
  ]
}

• urls (Zorunlu): Çözümlenecek Google Haritalar URL dizelerinin tekrar eden 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 Maps Grounding Lite herkese açık Issue Tracker bileşenini kullanın:

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