Google Places API Web Servisi Örnekleri ve Kapsamlı Kullanım Rehberi

Google Places API Web Servisi Örnekleri ve Kapsamlı Kullanım Rehberi

Giriş

Günümüzün dijital dünyasında konum tabanlı servisler, mobil uygulamaların ve web sitelerinin vazgeçilmez bir parçası haline gelmiştir. Kullanıcıların çevrelerindeki işletmeleri bulmasından, seyahat planlamasına, adres girişlerinden navigasyon sistemlerine kadar birçok alanda konum verileri hayati rol oynamaktadır. Bu ihtiyacı karşılamak üzere Google, geliştiricilere güçlü bir araç seti sunar: Google Places API. Bu API, dünya genelindeki milyonlarca yer hakkında zengin ve güncel verilere programatik erişim sağlayarak, uygulamaların kullanıcı deneyimini önemli ölçüde zenginleştirmesine olanak tanır.

Bu makale, Google Places API Web Servisi’nin temel bileşenlerini, nasıl kullanılacağını, farklı servis türlerini ve pratik uygulama örneklerini kapsamlı bir şekilde ele alacaktır. API anahtarı edinme sürecinden, çeşitli arama türlerine, detaylı yer bilgilerini çekmekten, otomatik tamamlama özelliklerine kadar birçok konuya değineceğiz. Ayrıca, maliyet optimizasyonu, güvenlik ve sıkça karşılaşılan sorunlara yönelik çözümler de makalemizin önemli bir parçası olacaktır. Amacımız, geliştiricilerin Google Places API’yi projelerinde etkin ve verimli bir şekilde kullanmalarına yardımcı olacak kapsamlı bir rehber sunmaktır.

Google Places API Nedir?

Google Places API, Google’ın devasa konum veritabanına programatik olarak erişim sağlayan bir web servisidir. Bu API sayesinde geliştiriciler, dünya genelindeki işletmeler, coğrafi ilgi çekici yerler, parklar, restoranlar, müzeler, oteller, alışveriş merkezleri ve daha birçok kategoriye ait milyonlarca yerin bilgilerine ulaşabilirler. API, bu yerlerin isimleri, adresleri, telefon numaraları, web siteleri, çalışma saatleri, kullanıcı değerlendirmeleri, fotoğrafları, coğrafi koordinatları ve hatta anlık doluluk durumları gibi çeşitli detayları sunar.

Temel Tanım ve Amacı: Places API’nin temel amacı, uygulamaların konum farkındalığını artırarak kullanıcılara daha zengin ve bağlamsal deneyimler sunmaktır. Örneğin, bir seyahat uygulaması, kullanıcının bulunduğu yere yakın popüler restoranları veya turistik yerleri gösterebilir. Bir e-ticaret uygulaması, kullanıcının en yakın mağazasını bulmasına yardımcı olabilir.

Sağladığı Veri Türleri:
* İşletme Bilgileri: Adı, adresi, telefon numarası, web sitesi, çalışma saatleri, kategori, değerlendirmeler.
* Coğrafi Konumlar: Enlem ve boylam koordinatları.
* Fotoğraflar: Yerlere ait yüksek kaliteli görseller.
* Kullanıcı Değerlendirmeleri: Diğer kullanıcıların yerler hakkındaki yorumları ve puanları.
* Anlık Durum Bilgileri: Bazı yerler için anlık doluluk veya bekleme süreleri gibi bilgiler.
* Adres Bileşenleri: Sokak, şehir, posta kodu, ülke gibi adresin parçaları.

Kullanım Alanları:
* Seyahat ve Gezi Uygulamaları: Kullanıcılara yakındaki ilgi çekici yerleri, otelleri, restoranları önerme.
* Konum Tabanlı Servisler: Kullanıcının konumuna göre özelleştirilmiş içerik sunma.
* E-ticaret ve Perakende: En yakın mağaza bulucular, teslimat adreslerinin doğrulanması.
* Navigasyon ve Harita Uygulamaları: Adres girişlerini otomatik tamamlama, POI (Point of Interest) arama.
* Sosyal Medya Uygulamaları: Kullanıcıların belirli bir yerde “check-in” yapmasına olanak tanıma.

Başlarken: API Anahtarı Edinme ve Proje Yapılandırma

Google Places API’yi kullanmaya başlamadan önce, Google Cloud Platform (GCP) üzerinde bir proje oluşturmanız ve bir API anahtarı edinmeniz gerekmektedir. Bu anahtar, uygulamanızın Google servislerine kimliğini doğrulamak ve kullanımınızı izlemek için kullanılır.

1. Google Cloud Platform Hesabı Oluşturma:
Eğer bir Google hesabınız yoksa, öncelikle bir Google hesabı oluşturmanız gerekmektedir. Ardından cloud.google.com adresine giderek Google Cloud Platform’a kaydolun. Yeni kullanıcılar genellikle ücretsiz deneme kredileriyle başlarlar.

2. Yeni Proje Oluşturma:
GCP konsoluna giriş yaptıktan sonra, üst menüdeki proje seçiciyi kullanarak yeni bir proje oluşturun veya mevcut bir projeyi seçin. Her API anahtarı belirli bir projeye bağlıdır.

3. Places API’yi Etkinleştirme:
Projenizi oluşturduktan veya seçtikten sonra, sol menüden “API’ler ve Hizmetler” -> “Kitaplık” bölümüne gidin. Arama çubuğuna “Places API” yazın ve çıkan sonuçlardan “Places API”yi seçerek “Etkinleştir” butonuna tıklayın. Bu işlem, projenizin Places API’yi kullanmasına izin verir.

4. API Anahtarı Oluşturma ve Kısıtlama:
API’yi etkinleştirdikten sonra, sol menüden “API’ler ve Hizmetler” -> “Kimlik Bilgileri” bölümüne gidin. “Kimlik Bilgileri Oluştur” butonuna tıklayın ve “API Anahtarı”nı seçin. Google otomatik olarak yeni bir API anahtarı oluşturacaktır.

Güvenlik Önlemleri ve API Anahtarını Kısıtlama:
Oluşturduğunuz API anahtarı, projenizin tüm Google servislerine erişim yetkisi verir. Bu nedenle, anahtarın güvenliğini sağlamak kritik öneme sahiptir. API anahtarınızı kısıtlamanız şiddetle tavsiye edilir:
* Uygulama Kısıtlamaları:
HTTP Referansları (Web siteleri): Anahtarın yalnızca belirli web sitelerinden (alan adlarından) gelen isteklere izin vermesini sağlayın. Örneğin, .example.com/*.
* IP Adresleri (Web sunucuları): Anahtarın yalnızca belirli sunucu IP adreslerinden gelen isteklere izin vermesini sağlayın.
* Android Uygulamaları: Anahtarın belirli Android paket adları ve SHA-1 parmak izleri ile kısıtlanmasını sağlayın.
* iOS Uygulamaları: Anahtarın belirli iOS paket kimlikleri ile kısıtlanmasını sağlayın.
* API Kısıtlamaları: Anahtarın yalnızca “Places API” gibi belirli API’leri kullanmasına izin verin. Bu, anahtarın çalınması durumunda yetkisiz erişimi sınırlar.

Bu kısıtlamalar, API anahtarınızın kötüye kullanılmasını önleyerek potansiyel maliyet artışlarının önüne geçer.

5. Faturalandırma (Billing) Ayarları:
Google Places API, ücretsiz kullanım katmanına sahip olsa da, çoğu kullanım senaryosu için bir faturalandırma hesabı gerektirir. API’yi kullanabilmek için projenize bir faturalandırma hesabı bağlamanız şarttır. Bu, “API’ler ve Hizmetler” -> “Faturalandırma” bölümünden yapılabilir. Google, çoğu API için aylık ücretsiz kredi sunar, ancak bu kredileri aşan kullanımlar ücretlendirilir. Faturalandırma hesabını bağlamak, API isteklerinizin işlenmesi için bir ön koşuldur.

Places API’nin Temel Servisleri

Google Places API, farklı ihtiyaçlara yönelik çeşitli servisler sunar. Bu servisler, RESTful mimarisi üzerinden HTTP istekleri aracılığıyla erişilebilir ve JSON formatında yanıtlar döner.

Place Search (Yer Arama)

Yer arama servisleri, belirli kriterlere göre yerleri bulmanızı sağlar.

Nearby Search (Yakın Çevre Araması)
* Açıklama: Belirli bir coğrafi konum (enlem/boylam) etrafındaki belirli bir yarıçap içindeki yerleri bulmak için kullanılır.
* Kullanım Senaryoları: “Bana en yakın restoranları göster”, “Bu otelin yakınındaki eczaneleri bul”.
* Temel Parametreler:
* location: Aramanın merkez noktası (enlem,boylam).
* radius: Aramanın yapılacağı yarıçap (metre cinsinden, maksimum 50.000).
* type: Aranacak yerin türü (örn. restaurant, cafe, hospital).
* keyword: Arama sonuçlarını filtrelemek için anahtar kelime (örn. “pizza”, “starbucks”).
* rankby: Sonuçları sıralama şekli (prominence varsayılan, distance mesafe).
* key: API anahtarınız.
* Örnek İstek URL’si:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&key=YOUR_API_KEY

* Örnek JSON Yanıtı (Kısaltılmış):

{
      "results": [
        {
          "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
          "name": "Sydney Opera House",
          "geometry": {
            "location": { "lat": -33.8567844, "lng": 151.2152967 }
          },
          "rating": 4.7,
          "vicinity": "Bennelong Point, Sydney"
        },
        // ... diğer sonuçlar
      ],
      "status": "OK"
    }

Text Search (Metin Araması)
* Açıklama: Serbest metin sorgularına dayalı yerleri aramak için kullanılır. Daha genel aramalar için idealdir. “İstanbul’daki en iyi kafeler”, “Ankara’da alışveriş merkezleri” gibi.
* Kullanım Senaryoları: Kullanıcının yazdığı metne göre yerleri bulma.
* Temel Parametreler:
* query: Metin tabanlı arama sorgusu (örn. “restoranlar New York”).
* location: (İsteğe bağlı) Aramanın ağırlıklandırılacağı merkez nokta.
* radius: (İsteğe bağlı) Konum etrafındaki yarıçap.
* type: (İsteğe bağlı) Yer türü.
* key: API anahtarınız.
* Örnek İstek URL’si:

https://maps.googleapis.com/maps/api/place/textsearch/json?query=best+restaurants+in+sydney&key=YOUR_API_KEY

* Örnek JSON Yanıtı (Kısaltılmış):

{
      "results": [
        {
          "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
          "name": "Quay",
          "formatted_address": "Upper Level, Overseas Passenger Terminal, The Rocks NSW 2000, Australia",
          "rating": 4.6
        },
        // ... diğer sonuçlar
      ],
      "status": "OK"
    }

Find Place (Yer Bul)
* Açıklama: Belirli bir metin girişi (örn. “Googleplex”) veya telefon numarasıyla bir yerin temel bilgilerini (place_id dahil) bulmak için kullanılır. Genellikle Place Details isteğinden önce bir yerin place_id‘sini elde etmek için kullanılır.
* Kullanım Senaryoları: Çok spesifik bir yerin bilgilerini almak.
* Temel Parametreler:
* input: Metin veya telefon numarası (örn. “Museum of Contemporary Art Australia”, “+61292507000”).
* inputtype: textquery veya phonenumber.
* fields: Yanıtta hangi alanların döndürüleceğini belirtir (örn. place_id, name, geometry). Bu parametre maliyet optimizasyonu için çok önemlidir.
* key: API anahtarınız.
* Örnek İstek URL’si:

https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Museum%20of%20Contemporary%20Art%20Australia&inputtype=textquery&fields=place_id,name,geometry&key=YOUR_API_KEY

* Örnek JSON Yanıtı (Kısaltılmış):

{
      "candidates": [
        {
          "place_id": "ChIJ_R-b0wOuEmsRzD7M4T-rXj0",
          "name": "Museum of Contemporary Art Australia",
          "geometry": { "location": { "lat": -33.860163, "lng": 151.209144 } }
        }
      ],
      "status": "OK"
    }

Place Details (Yer Detayları)

* Açıklama: Bir yerin place_id‘si kullanılarak o yere ait kapsamlı ve detaylı bilgileri almak için kullanılır. place_id, genellikle Place Search veya Find Place isteklerinden elde edilir.
* Kullanım Senaryoları: Kullanıcı bir arama sonucuna tıkladığında o yerin tüm detaylarını gösterme.
* Temel Parametreler:
* place_id: Detayları istenen yerin benzersiz kimliği.
* fields: Yanıtta döndürülecek alanları virgülle ayrılmış şekilde belirtir (örn. address_component, formatted_address, geometry, icon, name, opening_hours, photos, place_id, plus_code, rating, reviews, types, url, utc_offset, vicinity, website). Bu parametre, gereksiz veri çekimini engelleyerek maliyetleri düşürmek için kritik öneme sahiptir.
* key: API anahtarınız.
* Örnek İstek URL’si:

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJN1t_tDeuEmsRUsoyG83frY4&fields=name,rating,formatted_phone_number,geometry,opening_hours,website,photos,reviews&key=YOUR_API_KEY

* Örnek JSON Yanıtı (Kısaltılmış):

{
      "result": {
        "formatted_address": "Bennelong Point, Sydney NSW 2000, Australia",
        "name": "Sydney Opera House",
        "rating": 4.7,
        "formatted_phone_number": "(02) 9250 7777",
        "website": "https://www.sydneyoperahouse.com/",
        "opening_hours": {
          "open_now": true,
          "weekday_text": ["Monday: 9 AM – 5 PM", "Tuesday: 9 AM – 5 PM", / ... / ]
        },
        "photos": [
          {
            "height": 6000,
            "html_attributions": ["..."],
            "photo_reference": "CmRaAAA...", // Bu referans ile fotoğraf çekilir
            "width": 8000
          }
        ],
        "reviews": [
          {
            "author_name": "John Doe",
            "rating": 5,
            "text": "Amazing place, must visit!",
            "time": 1678886400
          }
        ]
      },
      "status": "OK"
    }

Place Photos (Yer Fotoğrafları)

* Açıklama: Bir yere ait fotoğrafları çekmek için kullanılır. Fotoğraf referansları, Place Details isteklerinden elde edilir. Bu servis, doğrudan bir görsel URL’si döndürür.
* Kullanım Senaryoları: Uygulama arayüzünde bir yerin görsellerini gösterme.
* Temel Parametreler:
* photoreference: Place Details yanıtından alınan fotoğraf referansı.
* maxwidth veya maxheight: İstenen fotoğrafın maksimum genişliği veya yüksekliği (piksel cinsinden, maksimum 1600).
* key: API anahtarınız.
* Örnek İstek URL’si:

https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photoreference=CmRaAAA...&key=YOUR_API_KEY

Bu URL, doğrudan fotoğrafın görüntülenebileceği bir URL’ye yönlendirme yapar.

Autocomplete (Otomatik Tamamlama)

* Açıklama: Kullanıcı bir metin kutusuna yazarken yer isimlerini ve adreslerini otomatik olarak tamamlama önerileri sunar. Kullanıcı deneyimini önemli ölçüde iyileştirir.
* Kullanım Senaryoları: Arama kutuları, adres giriş alanları.
* Temel Parametreler:
* input: Kullanıcının yazdığı metin (örn. “Eiffel T”).
* types: (İsteğe bağlı) Önerilerin türünü kısıtlar (örn. geocode sadece adresler, establishment sadece işletmeler).
* components: (İsteğe bağlı) Ülke gibi bileşenlere göre filtreleme (örn. country:tr).
* sessiontoken: (ÖNEMLİ) Her yeni otomatik tamamlama oturumu için benzersiz bir belirteç. Bu belirteç, tek bir otomatik tamamlama oturumu içindeki birden fazla isteği gruplandırarak maliyet optimizasyonu sağlar. Bir Place Details isteği yapıldığında oturum sona erer.
* key: API anahtarınız.
* Örnek İstek URL’si:

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Ankara%20Atat%C3%BCrk&types=geocode&components=country:tr&key=YOUR_API_KEY&sessiontoken=YOUR_SESSION_TOKEN

* Örnek JSON Yanıtı (Kısaltılmış):

{
      "predictions": [
        {
          "description": "Ankara Atatürk Lisesi, Ankara, Türkiye",
          "place_id": "ChIJG8WnK-0syhQRGqF-rY9Z_w",
          "structured_formatting": {
            "main_text": "Ankara Atatürk Lisesi",
            "secondary_text": "Ankara, Türkiye"
          },
          "terms": [ / ... / ]
        },
        // ... diğer öneriler
      ],
      "status": "OK"
    }

Geocoding ve Reverse Geocoding (Coğrafi Kodlama ve Ters Coğrafi Kodlama)

Bu servisler doğrudan Places API’nin bir parçası olmasa da (Google Maps Platform’un Geocoding API’sidir), konum tabanlı uygulamalarda Places API ile birlikte sıkça kullanılırlar.
* Geocoding (Coğrafi Kodlama): Bir adresi (örn. “1600 Amphitheatre Parkway, Mountain View, CA”) coğrafi koordinatlara (enlem ve boylam) dönüştürür.
* Reverse Geocoding (Ters Coğrafi Kodlama): Coğrafi koordinatları (enlem ve boylam) okunabilir bir adrese veya yer adına dönüştürür.
* Kullanım Senaryoları: Kullanıcının girdiği adresin haritada gösterilmesi, harita üzerindeki bir noktadan adres bilgisi alma.

Web Servisi İstekleri ve Yanıtları

Google Places API, RESTful prensiplere uygun bir web servisidir. Bu, HTTP protokolü üzerinden basit URL istekleri ile veri alışverişi yapıldığı anlamına gelir.

REST Prensipleri:
* Kaynak Tabanlı: Her yer (place), fotoğraf veya arama sonucu bir kaynaktır ve benzersiz bir URL ile tanımlanır.
* Durumsuz (Stateless): Her istek, sunucunun önceki istekler hakkında bilgi tutmasını gerektirmeyen tüm gerekli bilgileri içerir.
* İstemci-Sunucu Ayrımı: İstemci (uygulamanız) ve sunucu (Google API’leri) birbirinden bağımsızdır.

HTTP Metodları: Places API, çoğunlukla GET metodunu kullanarak veri çeker. Yani, istekler URL’nin bir parçası olarak gönderilen parametrelerle yapılır.

URL Yapısı:
Temel URL: https://maps.googleapis.com/maps/api/place/
Servis son noktası: nearbysearch/json, details/json, photo, autocomplete/json, vb.
Parametreler: ?key=YOUR_API_KEY¶m1=value1¶m2=value2

JSON Yanıt Formatı:
Tüm Places API servisleri (fotoğraf servisi hariç, o doğrudan görsel döner), yanıtlarını JavaScript Object Notation (JSON) formatında döner. JSON, hafif, okunabilir ve birçok programlama dili tarafından kolayca ayrıştırılabilir bir veri değişim formatıdır. Yanıt genellikle bir status alanı (isteğin başarılı olup olmadığını gösterir) ve results (arama servisleri için) veya result (detay servisleri için) gibi veri alanları içerir.

Hata Kodları ve Anlamları:
API yanıtında veya HTTP durum kodlarında karşılaşabileceğiniz bazı yaygın hata durumları:
* OK (200 HTTP): İstek başarıyla tamamlandı.
* ZERO_RESULTS: Arama için hiçbir sonuç bulunamadı.
* OVER_QUERY_LIMIT: Uygulamanız kota limitini aştı veya faturalandırma etkin değil.
* REQUEST_DENIED: İstek reddedildi (örn. geçersiz API anahtarı, API etkin değil, anahtar kısıtlamaları).
* INVALID_REQUEST: İstek URL’si veya parametreleri geçersiz.
* NOT_FOUND: İstenen yer place_id ile bulunamadı.
* UNKNOWN_ERROR: Sunucu tarafında bilinmeyen bir hata oluştu.

Güvenli API Anahtarı Kullanımı:
* Sunucu Tarafı (Backend): Eğer API isteklerini sunucunuzdan yapıyorsanız, API anahtarınızı ortam değişkenlerinde veya güvenli bir yapılandırma dosyasında saklayın. API anahtarınızı asla doğrudan kod içine gömmeyin veya sürüm kontrol sistemlerine (Git gibi) yüklemeyin. IP adresi kısıtlamalarını kullanın.
* İstemci Tarafı (Frontend): Tarayıcı tabanlı uygulamalarda (JavaScript ile) API anahtarınızı kullanırken, mutlaka HTTP referans kısıtlamalarını (alan adı kısıtlaması) kullanın. Bu, anahtarınızın başka web siteleri tarafından kötüye kullanılmasını önler. Asla genel bir API anahtarını kısıtlama olmadan tarayıcıda kullanmayın.

Uygulama Geliştirme Örnekleri

Google Places API’yi farklı programlama dillerinde ve ortamlarında nasıl kullanabileceğinize dair örnekler.

Python ile Places API Kullanımı

Python’da requests kütüphanesi ile basit bir Nearby Search örneği.

import requests
import json

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://maps.googleapis.com/maps/api/place/"

def nearby_search(location, radius, place_type, keyword=None):
    endpoint = "nearbysearch/json"
    params = {
        "location": f"{location['lat']},{location['lng']}",
        "radius": radius,
        "type": place_type,
        "key": API_KEY
    }
    if keyword:
        params["keyword"] = keyword

    response = requests.get(f"{BASE_URL}{endpoint}", params=params)
    response.raise_for_status() # HTTP hataları için istisna fırlatır
    return response.json()

def get_place_details(place_id, fields):
    endpoint = "details/json"
    params = {
        "place_id": place_id,
        "fields": ",".join(fields),
        "key": API_KEY
    }
    response = requests.get(f"{BASE_URL}{endpoint}", params=params)
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    # Örnek: İstanbul, Taksim Meydanı çevresindeki restoranları bul
    taksim_square = {"lat": 41.036109, "lng": 28.988241}
    
    print("Taksim çevresindeki restoranlar:")
    try:
        restaurants = nearby_search(taksim_square, 1500, "restaurant")
        if restaurants["status"] == "OK" and restaurants["results"]:
            for place in restaurants["results"][:5]: # İlk 5'i göster
                print(f"- {place['name']} (Place ID: {place['place_id']})")
                
                # İlk restoranın detaylarını çek
                if place == restaurants["results"][0]:
                    print("\nİlk restoranın detayları:")
                    details_fields = ["name", "formatted_address", "rating", "website", "formatted_phone_number", "opening_hours"]
                    place_details = get_place_details(place["place_id"], details_fields)
                    if place_details["status"] == "OK" and place_details["result"]:
                        result = place_details["result"]
                        print(f"  Adı: {result.get('name')}")
                        print(f"  Adres: {result.get('formatted_address')}")
                        print(f"  Puan: {result.get('rating')}")
                        print(f"  Web Sitesi: {result.get('website')}")
                        print(f"  Telefon: {result.get('formatted_phone_number')}")
                        if 'opening_hours' in result:
                            print(f"  Açık mı: {result['opening_hours'].get('open_now')}")
                            # print(f"  Çalışma Saatleri: {', '.join(result['opening_hours'].get('weekday_text', []))}")
                    else:
                        print(f"Detaylar çekilemedi: {place_details.get('status')}")
        else:
            print(f"Restoran bulunamadı veya hata: {restaurants.get('status')}")
    except requests.exceptions.RequestException as e:
        print(f"API isteği hatası: {e}")
    except Exception as e:
        print(f"Genel hata: {e}")

JavaScript (Node.js) ile Places API Kullanımı

Node.js ortamında node-fetch veya axios gibi kütüphanelerle Places API çağrıları yapılabilir.

const fetch = require('node-fetch'); // npm install node-fetch

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://maps.googleapis.com/maps/api/place/";

async function textSearch(query, location = null, radius = null) {
    const endpoint = "textsearch/json";
    let url = ${BASE_URL}${endpoint}?query=${encodeURIComponent(query)}&key=${API_KEY};
    
    if (location) {
        url += &location=${location.lat},${location.lng};
    }
    if (radius) {
        url += &radius=${radius};
    }

    try {
        const response = await fetch(url);
        if (!response.ok) {
            throw new Error(HTTP error! status: ${response.status});
        }
        return await response.json();
    } catch (error) {
        console.error("API isteği hatası:", error);
        return null;
    }
}

async function getPlaceDetails(placeId, fields) {
    const endpoint = "details/json";
    const url = ${BASE_URL}${endpoint}?place_id=${placeId}&fields=${fields.join(',')}&key=${API_KEY};
    
    try {
        const response = await fetch(url);
        if (!response.ok) {
            throw new Error(HTTP error! status: ${response.status});
        }
        return await response.json();
    } catch (error) {
        console.error("API detay isteği hatası:", error);
        return null;
    }
}

(async () => {
    // Örnek: "İzmir'deki en iyi kafeler" için metin araması
    console.log("İzmir'deki en iyi kafeler:");
    const izmirCafes = await textSearch("best cafes in Izmir");
    
    if (izmirCafes && izmirCafes.status === "OK" && izmirCafes.results.length > 0) {
        izmirCafes.results.slice(0, 3).forEach(place => { // İlk 3'ü göster
            console.log(- ${place.name} (Adres: ${place.formatted_address}));
        });

        // İlk kafenın detaylarını çek
        const firstCafeId = izmirCafes.results[0].place_id;
        console("\nİlk kafenın detayları:");
        const detailsFields = ["name", "formatted_address", "rating", "website"];
        const cafeDetails = await getPlaceDetails(firstCafeId, detailsFields);
        
        if (cafeDetails && cafeDetails.status === "OK" && cafeDetails.result) {
            console(  Adı: ${cafeDetails.result.name});
            console(  Adres: ${cafeDetails.result.formatted_address});
            console(  Puan: ${cafeDetails.result.rating});
            console(  Web Sitesi: ${cafeDetails.result.website || 'Yok'});
        } else {
            console(Detaylar çekilemedi: ${cafeDetails ? cafeDetails.status : 'Bilinmeyen hata'});
        }

    } else {
        console(Kafe bulunamadı veya hata: ${izmirCafes ? izmirCafes.status : 'Bilinmeyen hata'});
    }
})();

Frontend (Tarayıcı) Ortamında Places Autocomplete

Tarayıcıda otomatik tamamlama için Google Maps JavaScript API’nin Places kütüphanesi kullanılır. Bu, API anahtarını güvenli bir şekilde kullanmanıza ve kullanıcı arayüzü bileşenleriyle kolayca entegre olmanıza olanak tanır.

HTML:

    
    


    
Yer Otomatik Tamamlama
    
    
Seçilen Yer ID: 

    
    
    
    

Bu örnekte, libraries=places parametresi Places kütüphanesini yükler ve callback=initAutocomplete fonksiyonu API yüklendiğinde initAutocomplete fonksiyonunu çağırır. API anahtarınızı YOUR_API_KEY yerine yazmayı ve Google Cloud Console’da bu anahtar için HTTP Referans kısıtlaması eklemeyi unutmayın (örn. .yourdomain.com/).

Maliyet Optimizasyonu ve Güvenlik

Google Places API, kullanım başına ücretlendirilen bir servistir. Bu nedenle, maliyetleri optimize etmek ve API anahtarınızın güvenliğini sağlamak büyük önem taşır.

1. API Anahtarı Kısıtlamaları: Daha önce de belirtildiği gibi, API anahtarınızı kullanacağınız alan adları (HTTP referer), IP adresleri veya uygulama paket kimlikleri ile kısıtlayın. Bu, anahtarınızın kötü niyetli kişiler tarafından kullanılmasını engeller.

2. fields Parametresi ile Sadece Gerekli Veriyi Çekme: Place Details ve Find Place isteklerinde, fields parametresi ile yalnızca ihtiyacınız olan veri alanlarını isteyin. Her veri alanı farklı bir maliyete sahip olabilir. Örneğin, yalnızca bir yerin adını ve adresini istiyorsanız, name,formatted_address isteyin, reviews veya photos gibi daha pahalı alanları istemeyin.

3. Session Tokens Kullanımı (Autocomplete): Otomatik tamamlama için sessiontoken kullanmak, bir dizi otomatik tamamlama isteğini ve ardından gelen tek bir Place Details isteğini tek bir oturum olarak gruplandırır. Bu, maliyetleri önemli ölçüde düşürür, çünkü Google bu oturumu tek bir “Autocomplete Session” olarak faturalandırır. Her yeni arama oturumu için yeni bir sessiontoken oluşturun ve bir yer seçildiğinde veya arama tamamlandığında token’ı sıfırlayın.

4. Önbellekleme (Caching) Stratejileri: Sıkça istenen veya değişmeyen yer verilerini (örn. popüler yerlerin detayları) uygulamanızın sunucu tarafında veya istemci tarafında önbelleğe alın. Bu, aynı veri için tekrar tekrar API isteği yapmaktan kaçınarak maliyetleri düşürür. Ancak, verilerin güncel kalmasını sağlamak için uygun önbellek geçersiz kılma mekanizmaları uygulayın.

5. Kota Limitleri ve İzleme: Google Cloud Console’da API kullanımınızı ve kota limitlerinizi düzenli olarak izleyin. Anormal kullanım artışlarını veya OVER_QUERY_LIMIT hatalarını erkenden tespit ederek müdahale edebilirsiniz. Gerekirse kota limitlerinizi artırmak için Google’a talepte bulunabilirsiniz.

6. Client-side vs. Server-side İstekler: Hassas veriler içeren veya yüksek maliyetli API isteklerini sunucu tarafında (backend) yapmak daha güvenlidir. API anahtarınızın istemci tarafında (tarayıcıda) maruz kalma riskini azaltır. Ancak, Autocomplete gibi kullanıcı arayüzü odaklı servisler genellikle istemci tarafında daha iyi bir deneyim sunar.

Sıkça Sorulan Sorular ve İpuçları

“OVER_QUERY_LIMIT” hatası nasıl çözülür?
Bu hata, genellikle aşağıdaki nedenlerden biriyle ortaya çıkar:
* Kota Aşımı: Günlük veya dakikalık istek limitlerinizi aşmış olabilirsiniz. Google Cloud Console’dan kullanımınızı kontrol edin.
* Faturalandırma Etkin Değil: Projenize bir faturalandırma hesabı bağlı değilse veya kredi kartınızın süresi dolduysa bu hatayı alabilirsiniz.
* API Anahtarı Kısıtlaması: API anahtarınız yanlış kısıtlanmış olabilir ve isteğinize izin verilmiyor olabilir.
* Çözüm: Faturalandırma hesabınızın aktif olduğundan emin olun, kota limitlerinizi kontrol edin ve gerekirse artırın, API anahtarı kısıtlamalarını doğru yapılandırın.

“ZERO_RESULTS” ne anlama gelir?
Bu durum, API isteğinizin başarılı olduğu ancak belirtilen kriterlere uygun hiçbir yerin bulunamadığı anlamına gelir. Örneğin, çok küçük bir yarıçapla veya çok spesifik bir anahtar kelimeyle arama yaptığınızda bu yanıtı alabilirsiniz.

API yanıtında Türkçe karakter sorunları yaşanıyor mu?
Google Places API yanıtları genellikle UTF-8 kodlamasında gelir ve Türkçe karakterleri doğru şekilde destekler. Ancak, uygulamanızın karakter kodlama ayarları veya veritabanı ayarları yanlışsa sorun yaşayabilirsiniz. İstek ve yanıtları işlerken UTF-8’i kullandığınızdan emin olun.

Yerel dilde sonuç alma mümkün mü?
Evet, Places API isteklerine language parametresini ekleyerek sonuçların belirli bir dilde dönmesini sağlayabilirsiniz. Örneğin, language=tr ile Türkçe sonuçlar alabilirsiniz. Ancak, tüm yerlerin tüm dillerde çevirisi olmayabilir; bu durumda varsayılan veya İngilizce isimler dönebilir.

Farklı yer türlerini nasıl filtreleyebilirim?
type parametresini kullanarak belirli yer türlerini (örn. restaurant, cafe, hospital, atm) filtreleyebilirsiniz. Birden fazla tür belirtmek için pipe (|) karakterini kullanabilirsiniz (örn. type=restaurant|cafe). Ancak, bazı servislerde (örn. Autocomplete) types parametresi daha genel kategorileri (örn. geocode, establishment) kabul eder.

Sonuç ve Gelecek

Google Places API, konum tabanlı uygulamalar geliştiren geliştiriciler için paha biçilmez bir araçtır. Dünya genelindeki zengin ve güncel yer verilerine kolay erişim sağlayarak, uygulamaların kullanıcı deneyimini kişiselleştirme ve zenginleştirme potansiyeli sunar. Yakın çevre aramalarından detaylı yer bilgilerine, otomatik tamamlama özelliklerinden fotoğraf entegrasyonuna kadar geniş bir yelpazede servisler sunması, onu modern uygulama geliştirmenin ayrılmaz bir parçası haline getirmiştir.

Konum tabanlı servislerin ve akıllı şehir uygulamalarının yükselişiyle birlikte, Google Places API’nin önemi daha da artacaktır. Geliştiriciler, bu API’yi kullanarak seyahat planlama, yerel işletme keşfi, sosyal etkileşim ve lojistik gibi birçok alanda yenilikçi çözümler üretmeye devam edecektir. Maliyet optimizasyonu ve güvenlik en iyi uygulamalarını takip ederek, Google Places API’nin sunduğu tüm avantajlardan faydalanırken aynı zamanda sürdürülebilir ve güvenli uygulamalar geliştirmek mümkündür. Gelecekte, artırılmış gerçeklik (AR) ve yapay zeka (AI) ile entegrasyonlar sayesinde konum verilerinin kullanım alanları daha da genişleyecektir, bu da Places API gibi servislerin değerini katlayacaktır.