Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

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 çözümleyen toplu uç noktalar sağlar. Döndürülen yer kimliklerini diğer Google Haritalar Platformu API'leriyle kullanabilirsiniz. Her yanıt, çözümlenen yerleri Google Haritalar'da liste olarak kaydeden bir bağlantı da içerir.

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

Kapasite	REST yöntemi	MCP aracı
Konum adlarını veya adreslerini yerlerle eşleştirme	`resolveNames`	`resolve_names`
Google Haritalar URL'lerini yerlere çözümleme	`resolveMapsUrls`	`resolve_maps_urls`

Başlamadan önce

Resolution API'yi kullanmak için faturalandırmanın ve Maps Grounding Lite API hizmetinin etkinleştirildiği bir Google Cloud projeniz olmalıdır. 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ını hem de OAuth 2.0 kimlik bilgilerini destekler.

API anahtarı

X-Goog-Api-Key üstbilgisinde geçerli bir Google Haritalar Platformu API anahtarı ileterek veya 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: Proje başına dakikada 600 sorgu.
ResolveMapsUrls: Proje başına dakikada 600 sorgu.
Grup boyutu: İstek başına 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. Maps Grounding Lite'ın geri kalanı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 sıkı bir şekilde doğrulanır:

Toplu işlem boyutu sınırı: Her iki yöntem de istek başına en fazla 20 öğeye izin verir.
ResolveNames koşulları:
- queries içindeki her öğe, boş olmayan bir text parametresi belirtmelidir.
- Sorgular belirli bir yer adını veya adresi temsil etmelidir (örneğin, "Googleplex, Mountain View, CA" veya "Eyfel Kulesi, Paris").
- Genel kategori aramaları (ör. "İstanbul'daki restoranlar") veya konum içermeyen genel zincir adları (ör. "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 şunlardır:
  - Standart yer URL'si: https://www.google.com/maps/place/...
  - Kısaltılmış URL: https://maps.app.goo.gl/...
- Genel sorgu tabanlı Haritalar URL'leri (ör. 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ı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

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.
Hatalar için boş öğeler: i dizinindeki öğe çözümlenemezse sonuç listesi, i dizininde boş bir {} nesnesi içerir.
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.
saveToMapsUrl yalnızca başarılı işlemleri 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 aracında görebileceğiniz öğe bazlı hatalar listelenmiştir:

Yöntem	Neden	Kod	Mesaj
`ResolveNames`	Ad veya adres bir yerle eşleştirilemiyor.	`5` (`NOT_FOUND`)	`Place not found.`
`ResolveMapsUrls`	URL bir yerle eşleştirilemiyor.	`3` (`INVALID_ARGUMENT`)	`Failed to resolve Maps URL to a place.`
Her iki yöntem	Öğe çözümlenirken dahili bir hata oluştu.	`13` (`INTERNAL`)	`Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support`

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 Grounding Lite 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 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.

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ı 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 işlevini ç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 (örneğin, "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 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, bir geçerli yer URL'si ve bir yere çözümlenemeyen 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:

Maps Tools Resolution API Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Başlamadan önce

API erişimi ve kimlik doğrulama

API anahtarı

OAuth 2.0 kapsamları

Kullanım sınırları

Fiyatlandırma

İstek doğrulama ve kısıtlamalar

Çözümlenen yerleri Google Haritalar'a kaydetme

Kısmi hataları işleme

Yanıtı yorumlama

Öğe başına hatalar

Üst düzey hatalar

MCP ile Resolution API'yi kullanma

REST API spesifikasyonu ve curl örnekleri

ResolveNames

Yöntem: POST

İstek gövdesi biçimi

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

JSON yanıtı

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

JSON yanıtı

ResolveMapsUrls

Yöntem: POST

İstek gövdesi biçimi

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

JSON yanıtı

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

JSON yanıtı

Curl örneği: Doğrulama hatası

JSON yanıtı

Geri bildirim gönder

Maps Tools Resolution API