Android Google Haritalar’da İki Nokta Arası Rota Çizimi: Detaylı Teknik Rehber
Android platformunda coğrafi konum tabanlı uygulamalar geliştirirken, kullanıcıların iki nokta arasında bir rota çizebilmesi temel ve sıkça karşılaşılan bir gereksinimdir. Navigasyon uygulamalarından lojistik çözümlerine, seyahat planlama araçlarından konum tabanlı sosyal ağlara kadar pek çok alanda rota çizimi, kullanıcı deneyimini zenginleştiren kritik bir özelliktir. Google Haritalar SDK’sı, Android geliştiricilerine bu tür işlevselliği uygulamalarına entegre etme konusunda güçlü ve esnek bir yapı sunar. Bu detaylı teknik makale, Android Google Haritalar üzerinde iki nokta arasında nasıl rota çizileceğini, gerekli bileşenleri, API entegrasyonlarını ve adım adım uygulama süreçlerini kapsamlı bir şekilde ele alacaktır.
Giriş ve Temel Bileşenlere Genel Bakış
Google Haritalar SDK’sı, Android uygulamalarına etkileşimli haritalar eklemek için zengin bir API seti sağlar. Ancak, sadece harita göstermek yeterli değildir; kullanıcıların belirli bir hedefe ulaşmak için izlemesi gereken yolu görselleştirmek, uygulamanızın değerini artırır. Rota çizimi işlemi genellikle iki ana bileşenin birleşiminden oluşur: Google Haritalar SDK’sı (haritayı göstermek ve rotayı çizmek için) ve Google Directions API (başlangıç ve bitiş noktaları arasında rota verilerini almak için). Bu iki bileşeni doğru bir şekilde entegre etmek, başarılı bir rota çizim uygulamasının anahtarıdır.
Google Haritalar SDK for Android’e Genel Bakış
Google Haritalar SDK’sı, Android uygulamalarınıza tamamen özelleştirilebilir haritalar eklemenizi sağlar. Marker’lar, poligonlar, daireler ve çizgiler (polyline’lar) gibi çeşitli harita nesneleri eklemenize olanak tanır. Rota çizimi için, Directions API’den alınan rota verilerini bir Polyline nesnesi olarak haritaya ekleyeceğiz.
SDK’yı kullanmaya başlamak için öncelikle bir Google Cloud projesi oluşturmanız ve Haritalar SDK’sını etkinleştirmeniz gerekir. Ayrıca, uygulamalarınızın API’ye güvenli bir şekilde erişebilmesi için bir API anahtarı (API Key) almanız ve bunu uygulamanızın AndroidManifest.xml dosyasına eklemeniz gerekmektedir.
Gerekli İzinler ve Bağımlılıklar
Uygulamanızın harita ve konum servislerini kullanabilmesi için belirli izinlere ve bağımlılıklara ihtiyacı vardır:
* İnternet Erişimi: Directions API’ye istek göndermek ve harita döşemelerini indirmek için android.permission.INTERNET izni gereklidir.
* Konum İzinleri: Kullanıcının mevcut konumunu haritada göstermek isterseniz, android.permission.ACCESS_FINE_LOCATION ve/veya android.permission.ACCESS_COARSE_LOCATION izinlerini talep etmeniz gerekir. Android 6.0 (API 23) ve üzeri sürümlerde bu izinlerin çalışma zamanında (runtime) kullanıcıdan talep edilmesi gerektiğini unutmayın.
* Google Play Services: Google Haritalar SDK’sı, Google Play Services’a bağımlıdır. build.gradle dosyanıza aşağıdaki bağımlılığı eklemeniz gerekir:
implementation 'com.google.android.gms:play-services-maps:18.x.x'* Google Maps Utility Library (Opsiyonel ama Önerilir): Directions API’den alınan poliline kodunu çözmek için çok kullanışlıdır.
implementation 'com.google.maps.android:android-maps-utils:2.x.x'Harita Nesnesini Uygulamaya Entegre Etme
Haritayı uygulamanıza entegre etmek için iki ana yöntem vardır: SupportMapFragment veya MapView. Genellikle SupportMapFragment tercih edilir çünkü yaşam döngüsü yönetimini otomatik olarak halleder.
SupportMapFragment veya MapView Kullanımı
* SupportMapFragment: Bir Fragment olarak haritayı uygulamanızın bir bölümüne kolayca yerleştirmenizi sağlar. Aktivite yaşam döngüsü olaylarını otomatik olarak yönetir. XML layout dosyanızda aşağıdaki gibi tanımlanır:
Daha sonra aktivitenizde/fragment’ınızda bu fragmanı alıp getMapAsync() metodunu çağırarak harita hazır olduğunda bir geri çağırım (callback) alırsınız.
* MapView: Bir View olarak haritayı doğrudan bir layout’a yerleştirmenizi sağlar. Ancak, MapView‘in yaşam döngüsü olaylarını (onCreate, onStart, onResume, onPause, onStop, onDestroy, onSaveInstanceState) manuel olarak yönetmeniz gerekir. Daha fazla kontrol gerektiren özel durumlar için uygundur.
Her iki durumda da, harita hazır olduğunda OnMapReadyCallback arayüzü üzerinden onMapReady(GoogleMap googleMap) metodu çağrılır. Bu metot içinde GoogleMap nesnesine erişebilir ve harita üzerinde işlemler yapmaya başlayabilirsiniz.
Harita Ayarları ve Temel İşlemler
onMapReady metodu içinde GoogleMap nesnesini aldıktan sonra, haritanın görünümünü ve davranışını özelleştirebilirsiniz:
* Kamera Kontrolü: googleMap.moveCamera() veya googleMap.animateCamera() metodlarıyla haritanın görünümünü belirli bir LatLng noktasına veya LatLngBounds alanına taşıyabilirsiniz. CameraUpdateFactory sınıfı, kamera güncellemeleri oluşturmak için yardımcı metodlar sunar.
* Marker Ekleme: Belirli konumları işaretlemek için MarkerOptions nesnesi kullanarak googleMap.addMarker() metodunu çağırabilirsiniz. Marker’lar, rota başlangıç ve bitiş noktalarını görselleştirmek için önemlidir.
* UI Ayarları: Yakınlaştırma kontrolleri, konum butonu, harita türü (uydu, arazi vb.) gibi UI bileşenlerini etkinleştirebilir veya devre dışı bırakabilirsiniz.
Rota Çizimi İçin Gerekli Veri Kaynakları: Google Directions API
Doğrudan Google Haritalar SDK’sı ile rota çizmek mümkün değildir; sadece geometrik şekiller (polyline’lar) çizebilirsiniz. Asıl rota verisini elde etmek için Google Directions API’yi kullanmanız gerekir.
Google Directions API’ye Giriş
Google Directions API, belirli bir başlangıç noktası ile bir veya daha fazla hedef nokta arasında yol tarifi bilgileri sağlayan bir web servisidir. Bu API’yi kullanarak sürüş, yürüme, bisiklet veya toplu taşıma gibi farklı ulaşım modları için rota detaylarını alabilirsiniz. API, isteğe bağlı ara noktaları, alternatif rotaları ve trafik bilgilerini de destekler.
API’yi kullanabilmek için yine bir Google Cloud projesi ve etkinleştirilmiş “Directions API” hizmetine sahip olmanız gerekmektedir. Kullanım limitleri ve ücretlendirme politikalarını Google Cloud dokümantasyonundan incelemeniz önemlidir.
API İsteği Yapısı
Directions API’ye yapılan istekler genellikle bir HTTP GET isteği şeklinde olur ve aşağıdaki temel parametreleri içerir:
* origin: Başlangıç noktasının enlem ve boylamı (örn: 40.712776,-74.005974).
* destination: Bitiş noktasının enlem ve boylamı.
* mode: Ulaşım modu (örn: driving, walking, bicycling, transit).
* key: API anahtarınız.
* waypoints (Opsiyonel): Ara noktalar. Birden fazla ara nokta virgülle ayrılabilir. optimize:true parametresi ile en uygun sıra bulunabilir.
* alternatives (Opsiyonel): true olarak ayarlandığında, API birden fazla alternatif rota döndürebilir.
Örnek bir API isteği URL’si şu şekilde olabilir:
https://maps.googleapis.com/maps/api/directions/json?origin=40.712776,-74.005974&destination=40.758000,-73.985500&mode=driving&key=YOUR_API_KEY
API Yanıtının Ayrıştırılması
Directions API, yanıtı genellikle JSON formatında döndürür. Bu JSON yanıtı, rota bilgilerini içeren karmaşık bir yapıya sahiptir:
* routes: Bulunan rotaları içeren bir dizi. Genellikle en uygun rota ilk eleman olarak gelir.
* legs: Her rota, bir veya daha fazla “leg” (bacak) içerir. Her leg, bir başlangıç ve bitiş noktası arasındaki bir bölümü temsil eder.
* steps: Her leg, yol tarifinin ayrıntılı adımlarını içeren “step” (adım) dizisini barındırır.
* polyline: En kritik bilgi budur. Her route nesnesinin içinde, rotanın tüm geometrisini sıkıştırılmış bir dize olarak içeren bir overview_polyline nesnesi bulunur. Bu nesnenin points alanı, rotayı haritada çizmek için kullanacağımız kodlanmış poliline dizesini içerir.
Bu kodlanmış poliline dizesi, Google’ın kendi algoritmasıyla sıkıştırılmış bir dizi LatLng noktasıdır. Bu dizeyi tekrar LatLng nesnelerinin bir listesine dönüştürmek için PolyUtil.decode() metodunu (Google Maps Utility Library’den) kullanmamız gerekecektir.
Rota Çiziminin Adım Adım Uygulanması
Şimdi, yukarıda bahsedilen bileşenleri bir araya getirerek iki nokta arasında rota çizimi işlemini adım adım inceleyelim.
Adım 1: Kullanıcıdan Başlangıç ve Bitiş Noktalarını Alma
Kullanıcıdan başlangıç ve bitiş noktalarını almanın birkaç yolu vardır:
* Metin Girişi (EditText): Kullanıcıdan adres veya koordinat girmesini isteyebilirsiniz. Bu durumda, girilen adresleri koordinatlara çevirmek için Google Geocoding API’yi kullanmanız gerekebilir.
* Haritada Tıklama: Kullanıcının haritada bir noktaya tıklamasını sağlayarak GoogleMap.setOnMapClickListener() ile LatLng koordinatlarını alabilirsiniz.
* Mevcut Konum: Kullanıcının mevcut konumunu başlangıç noktası olarak ayarlayabilirsiniz. Bunun için FusedLocationProviderClient gibi konum servislerini kullanmanız gerekir.
Bu makalede, LatLng objelerine sahip olduğumuzu varsayarak ilerleyeceğiz.
Adım 2: Directions API İsteği Oluşturma
Directions API’ye bir HTTP isteği göndermeniz gerekir. Bu işlemi arka planda bir iş parçacığında yapmalısınız, çünkü ağ işlemleri UI iş parçacığını bloke edebilir ve ANR (Application Not Responding) hatalarına yol açabilir.
* Kullanılabilecek Kütüphaneler:
* HttpURLConnection: Android’in yerleşik HTTP istemcisi.
* OkHttp: Modern ve verimli bir HTTP istemcisi.
* Retrofit: REST API’leriyle çalışmak için tip güvenli bir HTTP istemcisi. Özellikle karmaşık API’ler için önerilir.
* Arka Plan İşlemleri:
* AsyncTask (eski): Basit işlemler için hala kullanılabilir.
* Kotlin Coroutines: Kotlin projeleri için modern ve önerilen eşzamansız programlama yaklaşımı.
* RxJava: Güçlü reaktif programlama kütüphanesi.
Örnek olarak, bir URL oluşturup bu URL’ye istek gönderen ve yanıtı okuyan bir metot düşünebiliriz:
// Örnek bir URL oluşturma
String url = "https://maps.googleapis.com/maps/api/directions/json?" +
"origin=" + startLatLng.latitude + "," + startLatLng.longitude +
"&destination=" + endLatLng.latitude + "," + endLatLng.longitude +
"&mode=driving" +
"&key=YOUR_API_KEY";
// Bu URL'ye arka planda bir HTTP isteği gönderin ve JSON yanıtını alın.
// Yanıtı bir String olarak döndürün.Adım 3: API Yanıtını İşleme ve Poliline Verisini Çıkarma
API’den gelen JSON yanıtını ayrıştırmanız gerekir. Bu işlem için Android’de yerleşik JSONObject ve JSONArray sınıflarını kullanabilir veya Gson gibi kütüphanelerden faydalanabilirsiniz.
1. JSON yanıtını JSONObject‘e dönüştürün.
2. "routes" dizisini alın.
3. Genellikle ilk rotayı (en uygun olanı) seçin.
4. Bu rotanın içindeki "overview_polyline" nesnesini ve onun "points" alanını alın. Bu alan, kodlanmış poliline dizesidir.
5. Bu dizeyi PolyUtil.decode(encodedPolylineString) metodu ile LatLng nesnelerinin bir listesine dönüştürün. Bu metod, Google Maps Utility Library’den gelir.
// Örnek JSON ayrıştırma mantığı
JSONObject jsonResponse = new JSONObject(jsonString);
JSONArray routes = jsonResponse.getJSONArray("routes");
if (routes.length() > 0) {
JSONObject route = routes.getJSONObject(0);
JSONObject overviewPolyline = route.getJSONObject("overview_polyline");
String encodedPolyline = overviewPolyline.getString("points");
// Poliline dizesini LatLng listesine dönüştür
List decodedPath = PolyUtil.decode(encodedPolyline);
// Şimdi bu decodedPath listesini kullanarak haritada rota çizebiliriz.
} Adım 4: Haritaya Poliline Çizme
LatLng listesini aldıktan sonra, bu listeyi kullanarak haritada bir poliline çizebilirsiniz.
1. Bir PolylineOptions nesnesi oluşturun.
2. add() metodunu kullanarak decodedPath listesindeki tüm LatLng noktalarını ekleyin.
3. Polilinenin rengini (color), genişliğini (width), şeffaflığını (alpha), başlangıç ve bitiş kapaklarını (startCap, endCap) ve birleşim stilini (jointType) ayarlayabilirsiniz.
4. googleMap.addPolyline(polylineOptions) metodunu çağırarak polilineyi haritaya ekleyin.
PolylineOptions polylineOptions = new PolylineOptions()
.addAll(decodedPath)
.width(10) // Piksel cinsinden genişlik
.color(Color.BLUE) // Rota rengi
.geodesic(true); // Gerçek dünya eğriliğini hesaba katma
googleMap.addPolyline(polylineOptions);Adım 5: Başlangıç ve Bitiş Noktalarına Marker Ekleme
Rotanın başlangıç ve bitiş noktalarını görselleştirmek için haritaya marker’lar eklemek iyi bir uygulamadır.
1. Başlangıç noktası için bir MarkerOptions nesnesi oluşturun, konumunu (position), başlığını (title) ve ikonunu (icon) ayarlayın.
2. Bitiş noktası için de benzer bir MarkerOptions nesnesi oluşturun.
3. googleMap.addMarker() metodunu çağırarak her iki marker’ı da haritaya ekleyin.
googleMap.addMarker(new MarkerOptions()
.position(startLatLng)
.title("Başlangıç Noktası")
.icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_GREEN)));
googleMap.addMarker(new MarkerOptions()
.position(endLatLng)
.title("Bitiş Noktası")
.icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_RED)));Adım 6: Harita Kamerasını Rotaya Odaklama
Rota çizildikten sonra, harita kamerasını tüm rotayı gösterecek şekilde ayarlamak kullanıcı deneyimini önemli ölçüde iyileştirir.
1. Bir LatLngBounds.Builder nesnesi oluşturun.
2. include() metodunu kullanarak başlangıç ve bitiş noktalarının LatLng‘lerini (veya rotadaki tüm noktaları) bu sınırlara dahil edin.
3. build() metodunu çağırarak LatLngBounds nesnesini oluşturun.
4. CameraUpdateFactory.newLatLngBounds(bounds, padding) metodunu kullanarak bir CameraUpdate oluşturun. padding parametresi, rotanın haritanın kenarlarına çok yakın olmamasını sağlar.
5. googleMap.animateCamera(cameraUpdate) metodunu çağırarak kamerayı rotaya odaklayın.
LatLngBounds.Builder builder = new LatLngBounds.Builder();
builder.include(startLatLng);
builder.include(endLatLng);
// İsteğe bağlı olarak, decodedPath'deki tüm noktaları da dahil edebilirsiniz:
// for (LatLng point : decodedPath) {
// builder.include(point);
// }
LatLngBounds bounds = builder.build();
int padding = 100; // Kenarlardan 100 piksel boşluk
CameraUpdate cu = CameraUpdateFactory.newLatLngBounds(bounds, padding);
googleMap.animateCamera(cu);Gelişmiş Özellikler ve Optimizasyonlar
Rota çizimi işlevselliğini daha da geliştirmek ve uygulamanızı optimize etmek için bazı ileri düzey konuları ele alalım.
Birden Fazla Rota ve Alternatifler
Directions API’ye yapılan istekte alternatives=true parametresini eklerseniz, API birden fazla olası rota döndürebilir. Bu durumda, JSON yanıtındaki routes dizisi birden fazla eleman içerecektir. Her bir rotayı ayrı ayrı ayrıştırıp haritada farklı renklerde veya stillerde poliline’lar olarak çizebilir ve kullanıcıya seçim yapma imkanı sunabilirsiniz.
Ara Noktalar (Waypoints) Kullanımı
Bazen kullanıcılar başlangıç ve bitiş noktaları arasında belirli duraklardan geçmek isteyebilir. waypoints parametresi ile Directions API’ye ara noktalar ekleyebilirsiniz. Bu ara noktalar virgülle ayrılmış LatLng koordinatları veya adresler olabilir. Ayrıca, waypoints=optimize:true|... parametresini kullanarak API’nin ara noktalar arasındaki en optimize edilmiş sırayı bulmasını sağlayabilirsiniz.
Rota Modları (Driving, Walking, Bicycling, Transit)
mode parametresini değiştirerek farklı ulaşım türleri için rota alabilirsiniz:
* driving (varsayılan): Araba ile sürüş.
* walking: Yürüme.
* bicycling: Bisiklet.
* transit: Toplu taşıma (genellikle departure_time veya arrival_time gibi ek parametreler gerektirir).
Uygulamanızda bir seçim arayüzü sunarak kullanıcının istediği ulaşım modunu seçmesine izin verebilirsiniz.
Hata Yönetimi ve Kullanıcı Geri Bildirimi
API istekleri başarısız olabilir veya geçerli bir rota bulunamayabilir. Bu durumları ele almak önemlidir:
* Ağ Hataları: İnternet bağlantısı yoksa kullanıcıya bilgi verin.
* API Yanıt Hataları: Directions API, status alanında ZERO_RESULTS, NOT_FOUND, OVER_QUERY_LIMIT gibi durum kodları döndürebilir. Bu durumları kontrol edin ve kullanıcıya uygun mesajlar gösterin (örn: “Bu iki nokta arasında rota bulunamadı”, “API kota aşıldı”).
* Konum Hataları: Kullanıcının girdiği konumlar geçersiz olabilir.
* Kullanıcı Arayüzü: Hata mesajlarını Toast, Snackbar veya AlertDialog ile gösterin. Yükleme göstergeleri (ProgressBar) kullanarak API isteği sırasında kullanıcıya geri bildirim sağlayın.
Performans Optimizasyonu
* Arka Plan İş Parçacıkları: Tüm ağ isteklerini ve yoğun JSON ayrıştırma işlemlerini ana UI iş parçacığından ayırarak uygulamanızın akıcı kalmasını sağlayın. AsyncTask, Coroutines veya RxJava gibi yapılar kullanın.
* Gereksiz Yeniden Çizimleri Önleme: Eğer rota verisi değişmediyse, haritayı tekrar tekrar çizmekten kaçının.
* Nesne Havuzlama: Çok sayıda marker veya poliline ekleyip çıkarıyorsanız, nesne havuzlama tekniklerini düşünebilirsiniz.
* Bellek Kullanımı: Özellikle uzun rotalar ve çok sayıda nokta için LatLng listelerinin bellek kullanımını göz önünde bulundurun.
Google Maps Utility Library Kullanımı
Daha önce bahsettiğimiz PolyUtil.decode() metodunun yanı sıra, Google Maps Utility Library başka kullanışlı araçlar da sunar:
* SphericalUtil: İki LatLng noktası arasındaki mesafeyi, alanı veya bearing’i hesaplamak gibi coğrafi hesaplamalar için.
* MarkerManager ve ClusterManager: Çok sayıda marker’ı verimli bir şekilde yönetmek ve yakın marker’ları kümelemek için.
Bu kütüphaneleri kullanarak geliştirme sürecinizi hızlandırabilir ve uygulamanızın performansını artırabilirsiniz.
Sıkça Karşılaşılan Sorunlar ve Çözümleri
Geliştirme sürecinde karşılaşabileceğiniz bazı yaygın sorunlar ve potansiyel çözümleri:
* API Key Hataları (API_KEY_INVALID, API_KEY_NOT_AUTHORIZED):
* API anahtarınızın doğru olduğundan ve AndroidManifest.xml dosyanızda doğru yere (
* Google Cloud Console’da Haritalar SDK’sı ve Directions API’nin etkinleştirildiğini kontrol edin.
* API anahtarınıza uygulamanızın paket adını ve SHA-1 parmak izini ekleyerek kısıtlamaları doğru yapılandırdığınızdan emin olun.
* Directions API Kota Aşımları (OVER_QUERY_LIMIT):
* Belirli bir zaman diliminde çok fazla istek gönderiyorsunuz demektir. API kullanımınızı optimize edin veya Google Cloud Console’dan kota artırımı talep edin (ücretli olabilir).
* Gereksiz isteklerden kaçınmak için rota verilerini önbelleğe almayı düşünebilirsiniz.
* SecurityException (İzin Eksikliği):
* AndroidManifest.xml dosyanızda gerekli INTERNET ve ACCESS_FINE_LOCATION gibi izinlerin tanımlandığından emin olun.
* Android 6.0 ve üzeri için çalışma zamanı izinlerini doğru bir şekilde talep ettiğinizden emin olun.
* Haritanın Yüklenmemesi (Gri Ekran):
* API anahtarınızın doğru olduğundan ve kısıtlamaların doğru yapılandırıldığından emin olun.
* Cihazda Google Play Services’ın güncel ve etkin olduğundan emin olun.
* Ağ bağlantısını kontrol edin.
* JSON Ayrıştırma Hataları:
* API yanıtının formatını dikkatlice inceleyin. Bazen API yanıtı beklenenden farklı bir yapıya sahip olabilir (örn: ZERO_RESULTS durumunda routes dizisi boş olabilir).
* try-catch blokları kullanarak JSON ayrıştırma hatalarını yakalayın.
Sonuç
Android Google Haritalar’da iki nokta arasında rota çizmek, modern mobil uygulamaların vazgeçilmez bir özelliğidir. Bu makalede, Google Haritalar SDK’sı ve Google Directions API’nin entegrasyonuyla bu işlevselliğin nasıl adım adım uygulanacağını detaylı bir şekilde ele aldık. API anahtarı kurulumundan, harita entegrasyonuna, Directions API isteği yapısından JSON yanıtını ayrıştırmaya ve polilineyi haritaya çizmeye kadar tüm süreçleri kapsadık. Ayrıca, alternatif rotalar, ara noktalar, farklı ulaşım modları, hata yönetimi ve performans optimizasyonu gibi gelişmiş konulara da değindik.
Bu rehberi takip ederek, uygulamanıza güçlü ve kullanıcı dostu bir rota çizim özelliği ekleyebilirsiniz. Unutmayın ki Google API’lerinin kullanım koşulları, kota limitleri ve ücretlendirme politikaları zaman zaman değişebilir, bu nedenle güncel dokümantasyonu düzenli olarak kontrol etmek önemlidir. Kullanıcı deneyimini en üst düzeye çıkarmak için görselleştirmeleri, hata yönetimini ve performans optimizasyonlarını daima ön planda tutmalısınız. Android ekosisteminin sunduğu esneklik ve Google Haritalar platformunun gücüyle, kullanıcılarınıza etkileyici ve işlevsel harita tabanlı deneyimler sunmaya hazırsınız.