Maps Tools Resolution API (deneysel)

Maps Tools Resolution API, konum adlarını ve URL'lerini Google Haritalar yer kimliklerine dönüştürmek için toplu işleme uç noktaları sağlar.

API Erişimi ve Kimlik Doğrulama

Kimlik Doğrulama Yöntemleri

API'ler hem API anahtarı hem de OAuth 2.0 kimlik bilgilerini destekler:

1. API Anahtarı

İstek URL'sine veya X-Goog-Api-Key üstbilgisine geçerli bir Google Haritalar Platformu API anahtarı ekleyerek isteklerin kimliğini doğrulayabilirsiniz:

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. OAuth 2.0 Kapsamları

OAuth yetkilendirmesi kullanılıyorsa aşağıdaki kapsamlar desteklenir:

  • https://www.googleapis.com/auth/maps-platform.mapstools (Önerilir)

İsteği Doğrulama 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:

  • Toplu İş Boyutu Sınırı: Her iki API de istek başına en fazla 20 öğeye izin verir.
  • ResolveNames Şartları:
    • Her sorgu öğesi, boş olmayan bir metin parametresi belirtmelidir.
    • Sorgular belirli bir yer adını veya adresi temsil etmelidir (ör. "Googleplex, Mountain View, CA", "Eyfel Kulesi, Paris").
    • Genel kategorik aramalar (ör. "New York'taki restoranlar") veya konum içermeyen genel zincir adları (ör. "Starbucks") desteklenmez ve çözümlenemeyebilir.
  • ResolveMapsUrls Şartları:
    • 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 (ör. https://maps.google.com/?q=restaurant) ve tek bir benzersiz yeri işaret etmeyen URL'ler desteklenmez.

Kısmi Hataları İşleme

Her iki API de toplu işleyici olarak tasarlanmıştır. Bir topludaki bazı öğeler çözümlenemezse genel istek, üst düzey bir hatayla başarısız olmaz. Bunun yerine API, Partial Success (Kısmi Başarı) yanıtı döndürür.

Yanıtı yorumlama

  1. 1:1 Eşleşme Garantisi: Döndürülen sonuçlar (ResolveNames için) veya öğeler (ResolveMapsUrls için) listeleri, giriş listesiyle 1:1 eşleşir.
  2. Hatalar İçin Boş Öğeler: i dizinindeki bir öğe çözümlenemezse sonuç listesi, i dizininde boş bir nesne {} içerir.
  3. failedRequests Map: Yanıtta failedRequests haritası var.
    • Anahtar, başarısız olan öğenin 0 tabanlı dizinidir (JSON'da dize olarak gösterilir).
    • Değer, belirli hata kodunu (standart gRPC/HTTP durumlarından) ve neden başarısız olduğunu açıklayan ayrıntılı bir mesajı içeren bir google.rpc.Status nesnesidir.

Üst Düzey Hatalar

Üst düzey bir HTTP hatası (ör. 400 Bad Request) yalnızca istek doğrulaması başarısız olursa (ör. 20'den fazla öğe iletilirken veya gerekli alanlar eksik olduğunda) döndürülür.

API Spesifikasyonu ve Curl Örnekleri

1. ResolveNames API

Yöntem: POST

https://mapstools.googleapis.com/v1alpha: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 tekrar eden 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", "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/v1alpha:resolveNames?key=KEY"
JSON yanıtı
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

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

Bu örnekte, ilk öğe çözümlenemeyen çöp 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/v1alpha:resolveNames?key=KEY"
JSON yanıtı
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

Yöntem: POST

https://mapstools.googleapis.com/v1alpha: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

Standart bir Google Haritalar yer bağlantısını çözme

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON yanıtı
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

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

Bir geçerli yer URL'si ve bir bozuk/desteklenmeyen URL'yi çözme

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON yanıtı
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

Curl örneği: Doğrulama hatası

Tek bir istekte 20'den fazla URL iletmeye çalışıyorsunuz.

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/v1alpha:resolveMapsUrls?key=KEY"
JSON yanıtı
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}