Google

Google Maps API Rehberi: Entegrasyon ve Geliştirme

Celil Uyanikoglu · 14 Mar 2026 · 11 dk okuma

Google Maps API Rehberi: Entegrasyon ve Geliştirme

Web ve mobil uygulamalara harita işlevselliği eklemek isteyen geliştiriciler için Google Maps Platform vazgeçilmez bir araç haline geldi. Restoran konumlarından kargo takibine, emlak ilanlarından seyahat planlamaya kadar pek çok sektörde harita entegrasyonu artık standart bir beklenti. Bu rehberde API anahtarı oluşturmadan fiyatlandırma detaylarına, temel entegrasyondan gelişmiş özelliklere kadar Google Maps API kullanımını ele alacağız.

Google Maps Platform Nedir?

Google Maps Platform, geliştiricilere harita, konum ve rota hizmetleri sunan bir API koleksiyonudur. Platform üç ana kategoride hizmet verir:

Maps: Statik ve dinamik haritalar, Street View görüntüleri, harita stilleri Routes: Yol tarifi, mesafe hesaplama, rota optimizasyonu Places: Yer arama, otomatik tamamlama, yer detayları, coğrafi kodlama

Her kategori kendi içinde birden fazla API barındırır. Projenizin ihtiyacına göre yalnızca kullanacağınız API'ları etkinleştirmeniz yeterlidir.

API Anahtarı Oluşturma

Google Maps API kullanmak için bir API anahtarı gereklidir. Anahtarı almak için Google Cloud Console üzerinden proje oluşturmanız ve faturalandırma hesabı bağlamanız gerekir.

Adım 1: Google Cloud Projesi Oluşturma

Google Cloud Console adresine gidin ve Google hesabınızla oturum açın. Üst menüden proje seçiciye tıklayıp "Yeni Proje" butonunu kullanın. Projeye açıklayıcı bir isim verin.

Adım 2: Faturalandırma Hesabı Bağlama

Google Maps Platform, ücretsiz kullanım limitleri sunsa da faturalandırma hesabı zorunludur. Sol menüden Faturalandırma bölümüne gidin ve bir ödeme yöntemi ekleyin. Ücretsiz limitler içinde kaldığınız sürece ücret yansımaz.

Adım 3: API Etkinleştirme

Sol menüden API ve Hizmetler bölümüne gidin. Kitaplık sekmesinden kullanmak istediğiniz API'yı arayın. Maps JavaScript API, Geocoding API veya Places API gibi seçeneklerden ihtiyacınız olanları etkinleştirin.

Adım 4: API Anahtarı Alma

Kimlik Bilgileri sayfasından Kimlik Bilgisi Oluştur menüsünden API Anahtarı seçeneğini tıklayın. Oluşturulan anahtarı güvenli bir yerde saklayın.

API Anahtarı Güvenliği

API anahtarınızı korumak için kısıtlamalar uygulamanız şarttır. Aksi halde kötü niyetli kişiler anahtarınızı kullanarak faturanızı şişirebilir.

HTTP yönlendirici kısıtlaması: Web projeleri için yalnızca belirli alan adlarından gelen isteklere izin verin. Örneğin *.siteniz.com şeklinde wildcard kullanabilirsiniz.

IP adresi kısıtlaması: Sunucu tarafı uygulamalar için yalnızca belirli IP adreslerinden gelen isteklere izin verin.

API kısıtlaması: Anahtarın yalnızca belirli API'lara erişmesini sağlayın. Maps JavaScript API için oluşturduğunuz anahtar Geocoding API'ya erişemesin.

Fiyatlandırma Sistemi

Google Maps Platform, kullanım başına ödeme modeliyle çalışır. 1 Mart 2025 itibarıyla fiyatlandırma sistemi yenilendi.

Yeni Ücretsiz Kullanım Limitleri

Eski sistemde aylık 200 dolarlık sabit kredi veriliyordu. Yeni sistemde her API için ayrı ücretsiz kullanım limiti tanımlandı:

API	Aylık Ücretsiz Limit
Maps JavaScript API (Dinamik Harita)	10.000 yükleme
Static Maps API	10.000 istek
Geocoding API	10.000 istek
Places Autocomplete	10.000 istek
Directions API / Routes API	10.000 istek
Street View Static API	5.000 istek

Ücretli Kullanım Fiyatları

Ücretsiz limiti aştığınızda bin istek başına ücretlendirme başlar:

Maps JavaScript API: 7 dolar / 1000 yükleme Static Maps API: 2 dolar / 1000 istek Geocoding API: 5 dolar / 1000 istek Places Autocomplete: 2,83 dolar / 1000 istek Routes API (Temel): 5 dolar / 1000 istek Street View: 14 dolar / 1000 istek

Hacim İndirimleri

Aylık kullanımınız arttıkça otomatik indirimler devreye girer. Örneğin Geocoding API için:

1 - 100.000 istek: 5 dolar / 1000
100.001 - 500.000 istek: 4 dolar / 1000
500.001 - 1.000.000 istek: 3 dolar / 1000
1.000.001 - 5.000.000 istek: 1,50 dolar / 1000
5.000.000+ istek: 0,38 dolar / 1000

Maps JavaScript API ile Harita Ekleme

Web sayfasına etkileşimli harita eklemek için Maps JavaScript API kullanılır.

Temel Harita Ekleme

HTML dosyanıza aşağıdaki kodu ekleyin:

<!DOCTYPE html>
<html>
<head>
    <title>Harita Örneği</title>
    <style>
        #map {
            height: 400px;
            width: 100%;
        }
    </style>
</head>
<body>
    <div id="map"></div>
    <script>
        function initMap() {
            const konum = { lat: 41.0082, lng: 28.9784 };
            const map = new google.maps.Map(document.getElementById("map"), {
                zoom: 12,
                center: konum
            });
            const marker = new google.maps.Marker({
                position: konum,
                map: map,
                title: "İstanbul"
            });
        }
    </script>
    <script async defer
        src="https://maps.googleapis.com/maps/api/js?key=API_ANAHTARINIZ&callback=initMap">
    </script>
</body>
</html>

Bu kod İstanbul merkezli bir harita oluşturur ve üzerine bir işaretçi ekler.

Harita Seçenekleri

Harita oluştururken çeşitli seçenekler tanımlayabilirsiniz:

zoom: Yakınlaştırma seviyesi (0-21 arası, 0 dünya görünümü) center: Harita merkezi (enlem ve boylam) mapTypeId: Harita türü (roadmap, satellite, hybrid, terrain) disableDefaultUI: Varsayılan kontrolleri gizleme zoomControl: Yakınlaştırma kontrolü mapTypeControl: Harita türü seçici streetViewControl: Street View kontrolü fullscreenControl: Tam ekran butonu

Gelişmiş İşaretçiler (Advanced Markers)

Google, 2024 sonunda klasik Marker sınıfını kullanımdan kaldırdı. Yeni projelerde AdvancedMarkerElement kullanmanız gerekiyor:

const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

const marker = new AdvancedMarkerElement({
    map: map,
    position: { lat: 41.0082, lng: 28.9784 },
    title: "İstanbul"
});

Gelişmiş işaretçiler özel HTML içerik, animasyon ve daha fazla özelleştirme imkanı sunar.

Geocoding API ile Adres Dönüştürme

Geocoding, adres metnini coğrafi koordinatlara dönüştürme işlemidir. Tersine geocoding ise koordinatları adrese çevirir.

Adres'ten Koordinat

const geocoder = new google.maps.Geocoder();

geocoder.geocode({ address: "Taksim Meydanı, İstanbul" }, (results, status) => {
    if (status === "OK") {
        const konum = results[0].geometry.location;
        console.log("Enlem:", konum.lat());
        console.log("Boylam:", konum.lng());
    }
});

Koordinat'tan Adres

geocoder.geocode({ location: { lat: 41.0082, lng: 28.9784 } }, (results, status) => {
    if (status === "OK") {
        console.log("Adres:", results[0].formatted_address);
    }
});

REST API Kullanımı

Sunucu tarafından Geocoding API'yı HTTP isteğiyle de çağırabilirsiniz:

https://maps.googleapis.com/maps/api/geocode/json?address=Taksim+Meydanı,İstanbul&key=API_ANAHTARINIZ

Yanıt JSON formatında döner ve formatted_address, geometry.location.lat, geometry.location.lng gibi alanlar içerir.

Places API ile Yer Arama

Places API, mekan bilgilerini aramak ve detaylarını almak için kullanılır.

Otomatik Tamamlama (Autocomplete)

Kullanıcının yazdığı metne göre yer önerileri sunar. 1 Mart 2025 itibarıyla yeni müşteriler için eski AutocompleteService kullanılamıyor. Bunun yerine PlaceAutocompleteElement kullanmanız gerekiyor:

const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
document.getElementById("search-container").appendChild(placeAutocomplete);

placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
    await place.fetchFields({ fields: ["displayName", "formattedAddress", "location"] });
    console.log(place.displayName);
    console.log(place.formattedAddress);
});

Yakındaki Yerler

Belirli bir konumun çevresindeki yerleri aramak için:

const service = new google.maps.places.PlacesService(map);

const request = {
    location: new google.maps.LatLng(41.0082, 28.9784),
    radius: 1000,
    type: ["restaurant"]
};

service.nearbySearch(request, (results, status) => {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
        results.forEach(place => {
            console.log(place.name, place.rating);
        });
    }
});

Yer Detayları

Bir yerin telefon, web sitesi, çalışma saatleri gibi detaylı bilgilerini almak için:

const request = {
    placeId: "ChIJN1t_tDeuEmsRUsoyG83frY4",
    fields: ["name", "formatted_phone_number", "opening_hours", "website"]
};

service.getDetails(request, (place, status) => {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
        console.log(place.name);
        console.log(place.formatted_phone_number);
    }
});

Routes API ile Yol Tarifi

Directions API'nın yerini alan Routes API, iki nokta arasındaki rotayı hesaplar.

Temel Rota Hesaplama

Routes API, POST isteği kullanır:

const response = await fetch("https://routes.googleapis.com/directions/v2:computeRoutes", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-Goog-Api-Key": "API_ANAHTARINIZ",
        "X-Goog-FieldMask": "routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline"
    },
    body: JSON.stringify({
        origin: {
            location: {
                latLng: { latitude: 41.0082, longitude: 28.9784 }
            }
        },
        destination: {
            location: {
                latLng: { latitude: 41.0422, longitude: 29.0083 }
            }
        },
        travelMode: "DRIVE"
    })
});

const data = await response.json();
console.log("Süre:", data.routes[0].duration);
console.log("Mesafe:", data.routes[0].distanceMeters, "metre");

Seyahat Modları

Routes API farklı ulaşım türlerini destekler:

DRIVE: Arabayla
BICYCLE: Bisikletle
WALK: Yürüyerek
TWO_WHEELER: Motosikletle
TRANSIT: Toplu taşımayla

Trafik Bilgisi

Gerçek zamanlı trafik verisiyle rota hesaplamak için routingPreference parametresini kullanın:

TRAFFIC_UNAWARE: Trafik dikkate alınmaz
TRAFFIC_AWARE: Trafik tahminleri kullanılır
TRAFFIC_AWARE_OPTIMAL: En doğru trafik verisi (daha yavaş yanıt)

API Anahtarı Olmadan Harita Ekleme

Basit kullanımlar için API anahtarı gerektirmeyen yöntemler de mevcuttur.

Google Maps Embed

Google Maps sitesinden paylaşım kodunu alarak iframe ile harita ekleyebilirsiniz:

Google Maps'te bir konum arayın
Paylaş butonuna tıklayın
Haritayı yerleştir sekmesinden HTML kodunu kopyalayın

<iframe
    src="https://www.google.com/maps/embed?pb=..."
    width="600"
    height="450"
    style="border:0;"
    allowfullscreen=""
    loading="lazy">
</iframe>

Bu yöntem ücretsizdir ancak özelleştirme imkanı sınırlıdır. Programatik kontrol, özel işaretçiler veya dinamik içerik ekleyemezsiniz.

Maps Embed API

Daha kontrollü embed için Maps Embed API kullanabilirsiniz. Bu API ücretsizdir ancak API anahtarı gerektirir:

<iframe
    src="https://www.google.com/maps/embed/v1/place?key=API_ANAHTARINIZ&q=Taksim+Meydanı,İstanbul"
    width="600"
    height="450">
</iframe>

Street View Entegrasyonu

Street View, 360 derece sokak görüntüleri sunar.

JavaScript ile Street View

const panorama = new google.maps.StreetViewPanorama(
    document.getElementById("street-view"),
    {
        position: { lat: 41.0082, lng: 28.9784 },
        pov: {
            heading: 165,
            pitch: 0
        }
    }
);

heading: Kameranın baktığı yön (0-360 derece) pitch: Kameranın dikey açısı (-90 ile 90 arası)

Street View Static API

Statik Street View görüntüsü almak için:

https://maps.googleapis.com/maps/api/streetview?size=600x400&location=41.0082,28.9784&heading=165&pitch=0&key=API_ANAHTARINIZ

Bu URL doğrudan img etiketinde kullanılabilir.

Hata Ayıklama ve Sorun Giderme

Yaygın Hatalar

InvalidKeyMapError: API anahtarı geçersiz veya kısıtlamalar yanlış ayarlanmış. Cloud Console'dan anahtarı ve kısıtlamaları kontrol edin.

RefererNotAllowedMapError: HTTP yönlendirici kısıtlaması alan adınızı engelliyor. Wildcard kullanıyorsanız *.siteniz.com formatında olduğundan emin olun.

ApiNotActivatedMapError: Kullanmaya çalıştığınız API etkinleştirilmemiş. Cloud Console'dan ilgili API'yı etkinleştirin.

OverQuotaMapError: Ücretsiz kota aşıldı ve faturalandırma hesabı bağlı değil veya limit ayarlanmış.

Kullanım Takibi

Cloud Console'daki API ve Hizmetler bölümünden kullanım istatistiklerini izleyebilirsiniz. Günlük ve aylık istek sayıları, hata oranları ve gecikme süreleri görüntülenir.

Bütçe Uyarıları

Beklenmedik maliyetlerden kaçınmak için bütçe uyarısı ayarlayın. Faturalandırma bölümünden bütçe limiti belirleyebilir ve eşik aşıldığında e-posta bildirimi alabilirsiniz.

Sık Sorulan Sorular

Google Maps API ücretsiz mi?

Her API için aylık ücretsiz kullanım limiti var. Küçük projeler bu limitler içinde kalabilir. Limitler aşıldığında kullanım başına ücret uygulanır.

API anahtarı olmadan harita kullanabilir miyim?

Google Maps sitesinden alınan embed kodu API anahtarı gerektirmez. Ancak programatik kontrol ve özelleştirme için API anahtarı zorunludur.

Directions API ile Routes API arasındaki fark nedir?

Directions API 1 Mart 2025 itibarıyla Legacy statüsüne alındı. Yeni projeler için Routes API kullanılması öneriliyor. Routes API daha iyi performans, gelişmiş özellikler ve genişletilmiş hacim indirimleri sunuyor.

Places Autocomplete neden çalışmıyor?

1 Mart 2025 sonrasında yeni müşteriler için eski AutocompleteService ve Autocomplete widget kullanılamıyor. PlaceAutocompleteElement kullanmanız gerekiyor.

Harita yüklenmiyor, neden?

API anahtarı kısıtlamalarını kontrol edin. HTTP yönlendirici kısıtlaması varsa alan adınızın listeye eklendiğinden emin olun. Tarayıcı konsolunda hata mesajını inceleyin.

Mobil uygulamada hangi API kullanılır?

Android için Maps SDK for Android, iOS için Maps SDK for iOS kullanılır. Bu SDK'lar platforma özel optimize edilmiştir.

API kullanımımı nasıl azaltabilirim?

Harita yüklemelerini önbelleğe alın, gereksiz API çağrılarından kaçının, Places API'da yalnızca ihtiyacınız olan alanları isteyin. Autocomplete için karaktere göre gecikme ekleyin.