Geoapify Routing API ile Rota ve Adım Adım Yol Tarifi Nasıl Alınır?

Günümüz dijital dünyasında konum tabanlı hizmetler, navigasyon uygulamaları ve lojistik çözümleri, günlük hayatımızın vazgeçilmez bir parçası haline gelmiştir. Bu tür uygulamaların temelini oluşturan en kritik bileşenlerden biri de doğru ve hızlı rota hesaplama yeteneğidir. Geoapify Routing API, geliştiricilere bu güçlü yeteneği sunarak, iki nokta arasında en uygun rotayı bulma ve kullanıcıya adım adım yol tarifleri sunma imkanı tanır. Bu makalede, Geoapify Routing API’nin nasıl kullanılacağını, temel özelliklerini ve adım adım yol tariflerini nasıl entegre edebileceğinizi detaylı bir şekilde inceleyeceğiz.

Geoapify Routing API’ye Giriş ve Temel Kavramlar

Geoapify Routing API, harita verilerini kullanarak coğrafi noktalar arasında en verimli rotaları hesaplamak için tasarlanmış güçlü bir araçtır. İster bir mobil uygulama geliştiriyor olun, ister bir lojistik yönetim sistemi, Geoapify’ın sunduğu esneklik ve doğruluk, projelerinizin başarısı için kritik öneme sahiptir.

Routing API Nedir?

Routing API, belirli başlangıç ve bitiş noktaları (ve isteğe bağlı olarak ara noktalar) arasında en uygun yolu bulmak için coğrafi verileri işleyen bir web servisidir. Bu servis, yol ağlarını, hız limitlerini, dönüş kısıtlamalarını ve hatta trafik koşullarını dikkate alarak en hızlı, en kısa veya en verimli rotayı belirler ve genellikle bir dizi koordinat (polyline) ve metinsel talimatlar (adım adım yol tarifleri) şeklinde bir yanıt döndürür.

Neden Geoapify Routing API?

Geoapify Routing API, kullanıcı dostu yapısı, geniş özellik yelpazesi ve uygun maliyetli çözümleriyle öne çıkar. Farklı ulaşım modlarını (araba, bisiklet, yaya vb.) desteklemesi, trafik verilerini entegre edebilmesi, özelleştirilebilir rota profilleri sunması ve küresel kapsama alanı ile birçok farklı kullanım senaryosuna uygun çözümler sunar. Ayrıca, detaylı dokümantasyonu ve aktif topluluk desteği sayesinde geliştirme süreci oldukça kolaydır.

Temel Terminoloji: Noktalar, Profiller, Modlar

Noktalar (Waypoints): Rota hesaplamasında kullanılan başlangıç, bitiş ve ara durak noktalarıdır. Genellikle enlem ve boylam koordinatları ile belirtilirler.
Profiller (Profiles): Rota hesaplamasının yapılacağı ulaşım türünü ve ilgili parametreleri tanımlar. Örneğin, car (araba), bicycle (bisiklet), pedestrian (yaya), truck (kamyon) gibi profiller mevcuttur. Her profilin kendine özgü hız limitleri, dönüş kısıtlamaları ve yol tercihleri bulunur.
Modlar (Modes): Genellikle profillerle birlikte kullanılır ve rota hesaplamasının temel amacını belirtir. Örneğin, drive (sürüş), walk (yürüme), cycle (bisiklet sürme).
Adım Adım Yol Tarifi (Turn-by-Turn Directions): Rotanın her bir aşamasında kullanıcıya hangi yöne gitmesi gerektiğini, ne kadar mesafe kat etmesi gerektiğini ve hangi eylemi (dönüş, kavşak geçişi vb.) yapması gerektiğini belirten metinsel talimatlardır.

Geoapify API Anahtarı Edinme ve Kurulum

Geoapify Routing API’yi kullanmaya başlamak için öncelikle bir API anahtarına ihtiyacınız olacak. Bu anahtar, isteklerinizi doğrulamak ve kullanımınızı izlemek için kullanılır.

API Anahtarı Nasıl Alınır?

Geoapify web sitesine (geoapify.com) gidin.
Ücretsiz bir hesap oluşturun veya mevcut hesabınızla giriş yapın.
Hesap panelinize ulaştığınızda, genellikle “API Keys” veya “My Projects” bölümünde size özel bir API anahtarı bulacaksınız. Bu anahtarı kopyalayın ve güvenli bir yerde saklayın.

Geoapify, ücretsiz katmanda belirli bir sayıda isteğe izin verir, bu da küçük projeler ve testler için idealdir. Daha büyük ölçekli uygulamalar için ücretli planlara geçiş yapmanız gerekebilir.

Güvenli Kullanım İçin En İyi Uygulamalar

API Anahtarınızı Gizli Tutun: API anahtarınızı asla herkese açık istemci tarafı kodunda (örn. frontend JavaScript) doğrudan yayınlamayın. Sunucu tarafında veya güvenli bir ortam değişkeni olarak saklayın.
Etki Alanı Kısıtlamaları: Geoapify panelinizde API anahtarınıza etki alanı (domain) kısıtlamaları ekleyerek, yalnızca belirli web sitelerinden gelen isteklerin kabul edilmesini sağlayabilirsiniz. Bu, anahtarınızın kötüye kullanılmasını önler.
IP Kısıtlamaları: Eğer API’yi bir sunucudan kullanıyorsanız, belirli IP adreslerinden gelen isteklere izin vererek güvenliği artırabilirsiniz.

Geliştirme Ortamı Hazırlığı

API isteklerini göndermek için herhangi bir programlama dilini kullanabilirsiniz. Genellikle web tabanlı uygulamalar için JavaScript (Node.js veya tarayıcı tarafı), Python, PHP veya cURL gibi araçlar tercih edilir. Bu makalede, hem cURL komutlarını hem de basit JavaScript örneklerini kullanarak konuyu açıklayacağız.

Rota Hesaplama Temelleri

Geoapify Routing API ile rota hesaplamak oldukça basittir. Temel olarak, başlangıç ve bitiş noktalarını API’ye göndermeniz yeterlidir.

İki Nokta Arası Rota İstekleri

En basit rota isteği, iki coğrafi nokta (başlangıç ve bitiş) arasında bir rota hesaplamaktır. Bu noktalar enlem ve boylam koordinatları ile belirtilir. API’ye yapılan istek genellikle bir HTTP GET isteğidir.


curl "https://api.geoapify.com/v1/routing?waypoints=52.520008,13.404954|52.521000,13.405000&mode=drive&apiKey=YOUR_API_KEY"

Yukarıdaki örnekte:

waypoints: Başlangıç ve bitiş noktalarının koordinatlarını enlem,boylam|enlem,boylam formatında belirtir.
mode: Ulaşım modunu belirtir (örneğin, drive - araba).
apiKey: Geoapify API anahtarınızdır.

Ara Noktalar (Waypoints) Ekleme

Tek bir başlangıç ve bitiş noktası yerine, birden fazla ara nokta (waypoint) ekleyerek daha karmaşık rotalar oluşturabilirsiniz. Bu, teslimat rotaları veya çok duraklı geziler için kullanışlıdır.


curl "https://api.geoapify.com/v1/routing?waypoints=52.520008,13.404954|52.521000,13.405000|52.522000,13.406000&mode=drive&apiKey=YOUR_API_KEY"

Bu örnekte, üç nokta arasında bir rota hesaplanacaktır. Geoapify API, bu noktaları verilen sıraya göre ziyaret edecek en uygun rotayı bulur.

Farklı Ulaşım Profilleri (Araba, Yaya, Bisiklet vb.)

Geoapify, farklı ulaşım modları için çeşitli profiller sunar. Bu profiller, rota hesaplamasının ilgili ulaşım türünün özelliklerine göre yapılmasını sağlar.

Profil (mode)	Açıklama
`drive`	Araba ile sürüş için optimize edilmiş rota.
`walk`	Yaya olarak yürüyüş için optimize edilmiş rota.
`bicycle`	Bisiklet sürüşü için optimize edilmiş rota.
`truck`	Kamyonlar için özel kısıtlamaları (yükseklik, ağırlık vb.) dikkate alan rota.

Profil seçimi, mode parametresi ile yapılır. Örneğin, bir yaya rotası için:


curl "https://api.geoapify.com/v1/routing?waypoints=52.520008,13.404954|52.521000,13.405000&mode=walk&apiKey=YOUR_API_KEY"

Örnek API İsteği ve Yanıt Yapısı

Bir rota isteği gönderdiğinizde, Geoapify API genellikle bir GeoJSON formatında yanıt döndürür. Bu yanıt, rotanın geometrisini (koordinat dizisi), mesafeyi, süreyi ve adım adım yol tariflerini içerir.

Basit bir JavaScript fetch isteği örneği:


async function getRoute() {
    const apiKey = 'YOUR_API_KEY';
    const start = '52.520008,13.404954'; // Berlin Brandenburg Kapısı civarı
    const end = '52.521000,13.405000'; // Yakın bir nokta
    const mode = 'drive';

    const url = https://api.geoapify.com/v1/routing?waypoints=${start}|${end}&mode=${mode}&apiKey=${apiKey};

    try {
        const response = await fetch(url);
        const data = await response.json();

        if (data.features && data.features.length > 0) {
            const route = data.features[0];
            console.log('Rota Mesafesi:', route.properties.distance, 'metre');
            console.log('Rota Süresi:', route.properties.time, 'saniye');
            console.log('Adım Adım Yol Tarifleri:', route.properties.instructions);
            // Rotanın geometrisi: route.geometry.coordinates
        } else {
            console.log('Rota bulunamadı.');
        }
    } catch (error) {
        console.error('Rota hesaplama hatası:', error);
    }
}

getRoute();

Yanıtın features[0].properties.instructions bölümü, adım adım yol tariflerini içeren bir dizi nesne barındırır. Her nesne, bir talimatı, mesafeyi, süreyi ve dönüş tipini detaylandırır.

Adım Adım Yol Tarifi (Turn-by-Turn Directions) Alma

Geoapify Routing API'nin en değerli özelliklerinden biri, kullanıcı dostu adım adım yol tarifleri sunmasıdır. Bu talimatlar, navigasyon uygulamaları için temel oluşturur.

Talimatların Yapısı ve Anlamı

API yanıtındaki instructions dizisi, rotanın her bir segmenti için ayrıntılı talimatlar içerir. Her talimat nesnesi genellikle şu bilgileri barındırır:

text: Kullanıcıya gösterilecek metinsel talimat (örn. "Sağa dönün", "Düz devam edin").
distance: Bu talimatın kapsadığı mesafe (metre cinsinden).
time: Bu talimatın kapsadığı tahmini süre (saniye cinsinden).
turn_angle: Dönüş açısı (varsa).
road_name: İlgili yolun adı.
exit_number: Kavşak çıkış numarası (varsa).

Metin Tabanlı ve Görsel Talimatlar

Geoapify API, varsayılan olarak metin tabanlı talimatlar sunar. Bu talimatları doğrudan uygulamanızın kullanıcı arayüzünde gösterebilirsiniz. Görsel talimatlar için ise, genellikle harita üzerinde oklar veya semboller kullanarak bu metinleri desteklemeniz gerekir. API'den gelen koordinatları kullanarak rotayı harita üzerinde çizebilir ve her talimat noktasına geldiğinde ilgili metni veya görseli gösterebilirsiniz.

Dil Seçenekleri ve Yerelleştirme

Geoapify Routing API, talimatları farklı dillerde döndürme yeteneğine sahiptir. lang parametresini kullanarak istediğiniz dili belirtebilirsiniz. Örneğin, Türkçe yol tarifleri almak için:


curl "https://api.geoapify.com/v1/routing?waypoints=52.520008,13.404954|52.521000,13.405000&mode=drive&lang=tr&apiKey=YOUR_API_KEY"

Bu özellik, uygulamanızı küresel kullanıcılara sunarken büyük kolaylık sağlar.

Örnek Kod: Adım Adım Yol Tarifleriyle Harita Entegrasyonu (Basit)

Aşağıdaki JavaScript örneği, bir rota isteği gönderir ve gelen talimatları konsola yazdırır. Gerçek bir uygulamada, bu talimatları bir harita kütüphanesi (örn. Leaflet, Mapbox GL JS) ile entegre ederek görsel bir navigasyon deneyimi sunabilirsiniz.


async function getTurnByTurnDirections() {
    const apiKey = 'YOUR_API_KEY';
    const start = '52.520008,13.404954'; // Başlangıç noktası
    const end = '52.521000,13.405000';   // Bitiş noktası
    const mode = 'drive';
    const lang = 'tr'; // Türkçe talimatlar

    const url = https://api.geoapify.com/v1/routing?waypoints=${start}|${end}&mode=${mode}&lang=${lang}&apiKey=${apiKey};

    try {
        const response = await fetch(url);
        const data = await response.json();

        if (data.features && data.features.length > 0) {
            const route = data.features[0];
            console.log('Rota Bilgileri:');
            console.log(Toplam Mesafe: ${route.properties.distance / 1000} km);
            console.log(Tahmini Süre: ${Math.round(route.properties.time / 60)} dakika);
            console.log('\nAdım Adım Yol Tarifleri:');

            route.properties.instructions.forEach((instruction, index) => {
                console.log(${index + 1}. ${instruction.text} (${instruction.distance} metre));
            });

            // Burada rotanın koordinatlarını (route.geometry.coordinates) kullanarak harita üzerinde çizebilirsiniz.
        } else {
            console.log('Rota veya talimat bulunamadı.');
        }
    } catch (error) {
        console.error('Hata:', error);
    }
}

getTurnByTurnDirections();

Gelişmiş Rota Özellikleri ve Optimizasyon

Geoapify Routing API, temel rota hesaplamasının ötesinde, daha karmaşık senaryoları destekleyen gelişmiş özellikler sunar.

Rota Kısıtlamaları (Yasaklı Bölgeler, Geçişler)

Bazı durumlarda, belirli bölgelerden geçişi kısıtlamak veya belirli yolları tercih etmek isteyebilirsiniz. Geoapify API, avoid_features veya include_features gibi parametrelerle bu tür kısıtlamaları uygulamanıza olanak tanır. Örneğin, otoyollardan kaçınmak veya belirli bir bölgeyi tamamen atlamak mümkündür. Bu özellikler, özellikle kamyon rotaları veya özel teslimat hizmetleri için önemlidir.

Trafik Verileriyle Rota Hesaplama

Gerçek zamanlı trafik verileri, özellikle yoğun şehirlerde en doğru rota hesaplaması için hayati öneme sahiptir. Geoapify Routing API, trafik verilerini entegre ederek, anlık trafik durumuna göre rotayı ve tahmini varış süresini güncelleyebilir. Bu özellik, traffic parametresi ile etkinleştirilebilir ve genellikle ücretli katmanlarda sunulur.


# Trafik verileriyle rota hesaplama örneği
curl "https://api.geoapify.com/v1/routing?waypoints=52.520008,13.404954|52.521000,13.405000&mode=drive&traffic=flow&apiKey=YOUR_API_KEY"

traffic=flow parametresi, akış tabanlı trafik verilerini kullanarak rota hesaplamasını sağlar.

En Hızlı ve En Kısa Rota Seçenekleri

Varsayılan olarak, Geoapify API genellikle en hızlı rotayı hesaplar. Ancak, bazı durumlarda en kısa rotayı tercih edebilirsiniz. API, bu seçenekleri doğrudan sunmasa da, profil ayarları ve ek parametrelerle bu tür optimizasyonları yapabilirsiniz. Örneğin, speed_factor gibi parametrelerle hızın veya mesafenin önemini ayarlayarak farklı rota türleri elde edilebilir.

Rota Optimizasyonu ve Çoklu Duraklar

Birden fazla durak noktası olan rotalar için (örneğin, kurye hizmetleri), Geoapify Routing API, bu durakları en verimli sıraya koyarak toplam seyahat süresini veya mesafesini minimize etme yeteneğine sahiptir. Bu özellik, "Travelling Salesperson Problem" (Gezgin Satıcı Problemi) olarak da bilinir ve optimize_waypoints gibi parametrelerle kullanılabilir. Bu, lojistik ve teslimat uygulamaları için kritik bir fonksiyondur.


# Çoklu duraklı rota optimizasyonu örneği
# NOT: Bu özellik genellikle daha gelişmiş API uç noktaları veya özel parametreler gerektirebilir.
# Geoapify'ın Dizin API'si (Directions API) veya Matrix API'si bu tür optimizasyonlar için daha uygun olabilir.
# Genel routing endpoint'i ile optimize_waypoints=true gibi bir parametre denenebilir.
curl "https://api.geoapify.com/v1/routing?waypoints=52.520008,13.404954|52.521000,13.405000|52.522000,13.406000&mode=drive&optimize_waypoints=true&apiKey=YOUR_API_KEY"

Geoapify Routing API Kullanım Senaryoları ve En İyi Uygulamalar

Geoapify Routing API'nin sunduğu yetenekler, geniş bir uygulama yelpazesinde kullanılabilir.

Navigasyon Uygulamaları

En bariz kullanım alanı, mobil veya web tabanlı navigasyon uygulamalarıdır. Kullanıcıların mevcut konumlarından hedeflerine en uygun rotayı bulmalarına ve adım adım yol tarifleriyle yönlendirilmelerine olanak tanır.

Lojistik ve Teslimat Yönetimi

Kargo ve teslimat şirketleri için, birden fazla teslimat noktasını en verimli şekilde ziyaret etmek, yakıt maliyetlerinden tasarruf etmek ve teslimat sürelerini optimize etmek kritik öneme sahiptir. Geoapify'ın rota optimizasyon ve trafik entegrasyon özellikleri bu alanda büyük fayda sağlar.

Gezi Planlama ve Turizm

Turizm uygulamaları, kullanıcıların ilgi çekici yerler arasında en iyi rotaları planlamalarına yardımcı olabilir. Yaya veya bisiklet profilleri ile şehir turları veya doğal parklardaki yürüyüş rotaları oluşturulabilir.

Performans ve Maliyet Yönetimi

Rota hesaplamalarını ve optimizasyonlarını doğru bir şekilde kullanarak, şirketler operasyonel maliyetlerini (yakıt, zaman) düşürebilir ve genel verimliliklerini artırabilirler. API'nin sunduğu mesafe ve süre bilgileri, maliyet analizleri için temel oluşturur.

Sonuç

Geoapify Routing API, geliştiricilere güçlü ve esnek bir rota hesaplama çözümü sunar. Temel iki nokta arası rotalardan, çok duraklı optimizasyonlara ve trafik entegrasyonuna kadar geniş bir yelpazede ihtiyaçları karşılayabilir. API anahtarınızı edinerek ve yukarıdaki örnekleri takip ederek, kendi konum tabanlı uygulamalarınızda Geoapify'ın gücünden yararlanmaya hemen başlayabilirsiniz. Doğru ve güncel rota bilgileriyle kullanıcılarınıza kusursuz bir deneyim sunmak artık çok daha kolay.

SSS (Sık Sorulan Sorular)

Geoapify API ücretsiz mi?

Evet, Geoapify, küçük ölçekli projeler ve testler için yeterli olan ücretsiz bir kullanım katmanı sunar. Daha yüksek kullanım limitleri ve gelişmiş özellikler için ücretli planlara geçiş yapmanız gerekebilir.

Hangi ulaşım modlarını destekliyor?

Geoapify Routing API; araba (drive), yaya (walk), bisiklet (bicycle), kamyon (truck) gibi popüler ulaşım modlarını destekler. Her mod için özel rota algoritmaları ve kısıtlamaları uygulanır.

Trafik verilerini kullanabilir miyim?

Evet, Geoapify Routing API, gerçek zamanlı trafik verilerini rota hesaplamalarına dahil etme yeteneğine sahiptir. Bu özellik genellikle ücretli planlarda sunulur ve rota sürelerinin daha doğru tahmin edilmesini sağlar.

Çoklu duraklı rota hesaplayabilir miyim?

Evet, API'ye birden fazla ara nokta (waypoint) göndererek çok duraklı rotalar hesaplayabilirsiniz. Ayrıca, bu durakları en verimli sıraya koymak için rota optimizasyonu özelliklerini de kullanabilirsiniz.

API anahtarımı nasıl korumalıyım?

API anahtarınızı asla herkese açık istemci tarafı kodunda doğrudan yayınlamayın. Sunucu tarafında veya güvenli ortam değişkenleri olarak saklayın. Ayrıca, Geoapify panelinizden API anahtarınıza etki alanı (domain) veya IP kısıtlamaları ekleyerek güvenliği artırabilirsiniz.

Geoapify Routing API ile Rota ve Adım Adım Yol Tarifi Nasıl Alınır?