Google Maps API Nasıl Entegre Edilir? Pratik Rehber

Bir e-ticaret sitesine teslimat haritası eklemek ya da bir emlak ilanına konum işaretlemek gerektiğinde iş genelde aynı noktaya çıkar: Google Maps Platform. Anahtar alımından maliyet kontrolüne kadar, kurulumda gerçekten karşılaşacağınız adımları aşağıda sırasıyla ele alıyoruz; kopyala-yapıştır kod örnekleri de dahil.

Google Maps API tam olarak neyi kapsıyor?

"Google Maps API" tek bir servis değil, birbirinden bağımsız çalışan bir API ailesidir. Maps JavaScript API sayfaya etkileşimli harita gömer. Geocoding API bir adresi enlem-boylam koordinatına çevirir, Places API işletme ve adres önerileri döndürür, Directions API iki nokta arasındaki rotayı hesaplar, Distance Matrix API ise çoklu nokta arasındaki mesafe ve süre matrisini çıkarır.

Her biri ayrı bir uç nokta, ayrı bir kota ve ayrı bir fatura kalemidir. Projenize hangi API'lerin gerekli olduğunu baştan netleştirmek hem kodu sadeleştirir hem de faturayı büyütmez. Bir teslimat uygulaması genelde dördünü birden kullanır; basit bir "bize ulaşın" sayfası ise yalnızca JavaScript API ile yetinir.

API anahtarını nasıl alır, nasıl korursunuz?

Google Cloud Console'da yeni bir proje açıp Maps JavaScript API, Geocoding API gibi ihtiyaç duyduğunuz servisleri etkinleştirdikten sonra "Credentials" sekmesinden bir API anahtarı üretirsiniz. Bu anahtar olmadan hiçbir istek geçmez.

Anahtarı ürettiğiniz anda kısıtlama eklemeden bırakmayın. Korumasız bir anahtarı biri bulup kendi projesinde kullanmaya başladığı an fatura size yansır. Google Cloud Console üzerinden iki tür kısıtlama tanımlarsınız:

• Uygulama kısıtlaması: HTTP yönlendirici (belirli domainler), IP adresi veya Android/iOS paket adı
• API kısıtlaması: anahtarın yalnızca etkinleştirdiğiniz servisleri çağırabilmesi

Anahtarı .env dosyasında tutup .gitignore'a eklemek, GitHub gibi herkese açık depolara sızmasının önüne geçen en basit adımdır. Sızan bir anahtarı fark ettiğinizde Cloud Console'dan hemen iptal edip yenisini üretin.

JavaScript ile harita nasıl gömülür?

En temel entegrasyon üç parçadan oluşur: bir script etiketi, bir div konteyneri ve haritayı başlatan JavaScript kodu.

<div id="harita" style="height: 400px;"></div>
<script src="https://maps.googleapis.com/maps/api/js?key=API_ANAHTARINIZ&callback=initMap" async defer></script>

function initMap() {
  const merkez = { lat: 41.0082, lng: 28.9784 };
  const harita = new google.maps.Map(document.getElementById("harita"), {
    zoom: 13,
    center: merkez,
  });
  new google.maps.Marker({ position: merkez, map: harita });
}

Bir adresi koordinata çevirmek için Geocoding API'yi çağırırsınız; dönen lat/lng değerini doğrudan marker'a verirsiniz. Places Autocomplete ile arama kutusu eklemek isterseniz google.maps.places.Autocomplete sınıfını input alanına bağlamanız yeterlidir. Directions Service ise başlangıç ve bitiş noktasını alıp DirectionsRenderer ile rotayı haritaya çizer.

Geliştirme sırasında her adımı ayrı test edin: önce boş harita çıksın, sonra marker eklensin, sonra arama kutusu devreye girsin. Her şeyi tek seferde bağlamaya çalışmak, hatanın hangi satırdan geldiğini bulmayı zorlaştırır.

Maliyeti nasıl kontrol altında tutarsınız?

Maps Platform kullanım bazlı faturalandırılır; her Geocoding çağrısı, her harita yüklemesi ayrı sayılır. Google aylık belirli bir ücretsiz kullanım kredisi tanımlar; bu miktar küçük projeler ve geliştirme aşaması için genelde yeterlidir. Ancak trafik büyüdükçe fatura da büyür.

Pratikte dört önlem işe yarıyor:

Özellikle Autocomplete kutusu, kullanıcı her tuşa bastığında istek atabildiği için maliyeti sessizce yükseltebilir. Debounce (kısa gecikmeli tetikleme) eklemek bu riski büyük ölçüde azaltır.

Google Maps'e alternatif ne var?

Google Maps en kapsamlı işletme verisine ve en geniş ekosisteme sahiptir, ama tek seçenek değildir. Açık kaynaklı harita verisiyle çalışan kütüphaneler (OpenStreetMap tabanlı çözümler gibi), maliyet hassasiyeti olan veya veri kontrolünü kendi elinde tutmak isteyen projeler için ciddi bir alternatiftir. Temel harita gösterimi, marker ekleme ve rota çizme gibi ihtiyaçların çoğunu karşılarlar; eksik kaldıkları nokta genelde Places API'nin sunduğu zengin işletme veritabanıdır.

Ticari alternatif sağlayıcılar da farklı fiyatlandırma modelleriyle mevcuttur. Seçim, projenizin veri derinliği ihtiyacına ve bütçesine bağlıdır: en kapsamlı veri gerekiyorsa Google Maps öne çıkar, maliyet veya bağımsızlık öncelikliyse açık kaynak seçenekleri değerlendirmeye değer.

Harita performansını nasıl optimize edersiniz?

Harita, sayfanın en ağır bileşenlerinden biri olabilir; dikkatsiz bir entegrasyon sayfa açılış hızını doğrudan düşürür. Harita katlanmanın altındaysa, yani sayfa ilk açıldığında görünmüyorsa, kullanıcı o bölüme kaydırana kadar script'i yüklememek gerçek bir fark yaratır.

Çok sayıda marker içeren haritalarda MarkerClusterer gibi bir kümeleme kütüphanesi kullanmak hem render süresini kısaltır hem de haritayı okunur tutar; yüzlerce nokta üst üste bindiğinde harita zaten kullanılamaz hale gelir. Mobil cihazlarda dokunmatik etkileşimin sorunsuz çalıştığını ayrıca test edin, çünkü trafiğin büyük kısmı mobil cihazlardan geliyor. Yükleme sırasında bir iskelet gösterge (skeleton/spinner) koymak ve API hatasını sessizce yutmak yerine kullanıcıya anlaşılır bir mesaj göstermek, küçük ama fark edilen iyileştirmelerdir.

Teslimat uygulamalarında Geocoding, Places, Directions ve Distance Matrix genelde birlikte çalışır: adres doğrulanır, en yakın seçenekler listelenir, rota çizilir, süre tahmin edilir. Emlak sitelerinde ise ağırlık Places ve JavaScript API'de toplanır; ilan konumu ve çevredeki okul, market gibi noktalar işaretlenir. Hangi servisleri birlikte kullanacağınızı önceden planlamak, sonradan API eklemekten çok daha az yeniden yazım gerektirir.

Daha fazla teknik detay için Google Maps Platform dokümantasyonuna ve API arayüzü tasarım ilkeleri için MDN'in API rehberine bakabilirsiniz. SEO tarafında haritalı sayfaların nasıl indekslendiğini merak ediyorsanız Google Arama Konsolu rehberimize göz atın.

Yazan Celil Uyanikoglu

Bilgisayar mühendisiyim; 25 yılı aşkın süredir bilgi işlem sektörünün içindeyim. Bu blogu 2020'de, işimde her gün karşılaştığım sorunların çözümlerini bir yere yazmak için açtım: Linux, güvenlik, tarayıcılar, yapay zeka araçları. Yazdığım her rehberi önce kendi bilgisayarımda ya da sunucumda deniyorum; çalıştığını görmediğim adımı yayınlamam. Hatalı ya da eskimiş bir şey görürsen iletişim sayfasından yaz — düzeltirim.