Geocode, bir adresi yeryüzünde tek bir noktaya sabitleyen koordinattır. İnsan diliyle yazılmış yer adları ("10 Downing Street, London") ile makinece okunabilir geometri (51.5034, -0.1276) arasındaki köprüdür. Şimdiye kadar tıkladığınız her harita iğnesi, dokunduğunuz her "buraya teslim et" düğmesi ve çalıştırdığınız her "yakındakileri göster" sorgusu, yığının bir yerinde bir geocode tarafından besleniyordu.
Bu kılavuz, geocode'un gerçekte ne olduğunu, forward ve reverse geocoding'in nasıl farklılaştığını, üretim seviyesinde bir geocoding API'sinin neler döndürdüğünü ve sık karşılaşılan tuzakların nerede saklandığını anlatıyor.
Geocode Aslında Nedir
En dar anlamıyla geocode, yeryüzünde tek bir noktadır ve bilinen bir datumda (neredeyse her zaman WGS84, telefonunuzun GPS'inin kullandığı datumun aynısı) bir enlem ve boylam çifti olarak ifade edilir. Enlem -90'dan (Güney Kutbu) +90'a (Kuzey Kutbu) kadar uzanır. Boylam -180 ile +180 arasındadır ve 0, Greenwich meridyenindedir.
Bu dar tanımın dışında "geocode" terimi gevşek biçimde "bir adresi geocoding API'sinden geçirmenin sonucu" anlamında da kullanılır; bu sonuç genellikle koordinatın yanına bir dizi ilgili meta veri ekler: normalleştirilmiş adres, bir yer kimliği, hassasiyet kademesi, güven puanı ve sınırlayıcı kutu. Üretim kodunda gerçekten saklayıp üzerinde işlem yaptığınız nesne işte bu zengin nesnedir.
Tek başına bir koordinat size nerede olduğunu söyler. Meta veri ise o "nere"ye ne kadar güvenmeniz gerektiğini söyler.
Forward ve Reverse Geocoding
İki yön vardır ve aynı API endpoint'i genellikle ikisini de işler.
Forward geocoding metni koordinata çevirir. Girdi: "Eyfel Kulesi, Paris". Çıktı: 48.8584, 2.2945, eşleşen yer türü (bu örnekte landmark), idari kırılım (Paris, Île-de-France, Fransa) ve özelliğin sınırlayıcı kutusu.
Reverse geocoding koordinatı metne çevirir. Girdi: 48.8584, 2.2945. Çıktı: yapılandırılmış bir adres (Avenue Gustave Eiffel, 75007 Paris, Fransa), yer türü ve genellikle yakındaki ilgi noktalarının bir listesi.
Forward, ödeme adımındaki otomatik tamamlamayı, mağaza bulucuları ve CSV-haritaya aktarım hatlarını besler. Reverse ise "Yakınımdan teslim al" düğmelerini, geotag'lı fotoğrafları ve kullanıcının haritada bir iğne bıraktığı, uygulamanın da o iğneye bir ad bulması gereken her özelliği besler.
Bir Geocoding API Ne Döner
Tek başına bir koordinat, bir özelliği yayına almaya yetmez. Ciddi bir geocoding API, kodda karar vermenizi sağlayan yapılandırılmış bir nesne döner. Önemli alanlar:
latitude/longitudeWGS84 datumundaformatted_address: gösterim için normalleştirilmiş, kanonik adres metniplace_id: saklayıp daha sonra yeniden çözebileceğiniz kararlı bir tanımlayıcıprecision(bazenmatch_typeveyaaccuracy): rooftop, sokak, mahalle, posta kodu, yerleşim yeri ya da ülke. İş kararları verirken en kritik tek alandırconfidence: API'nin ne kadar emin olduğunu gösteren sayısal puan (genellikle 0 ile 1 arası)bbox: eşleşen özelliğin sınırlayıcı kutusu, haritayı sonuca sığdırmak için faydalıdıraddress_components: adresin yapılandırılmış parçalara ayrılmış hali (sokak, numara, şehir, bölge, ülke, posta kodu)country_code: ISO 3166-1 alpha-2 formatında
İki gerçek kaydın hassasiyeti birbirinden çok farklı olur. Bir teslimat göndermeden önce konut adresi için rooftop eşleşmesi istersiniz. "Bana en yakın mağazayı göster" için posta kodu seviyesindeki bir eşleşme yeterlidir. Bir locality eşleşmesi yalnızca şehri bildiğiniz anlamına gelir; bu da onay almadan harekete geçmek için neredeyse hiçbir zaman yeterli değildir.
Geocode'lar Nerede Kullanılır
Geocode'lar, konum bilinçli ürün özelliklerinin çoğunun altında sessizce çalışır.
- Adres otomatik tamamlama: ödeme formundaki her tuş vuruşu, sıralanmış aday eşleşmeleri döndüren bir forward geocode tetikler
- Mağaza ve mekan bulucular: kullanıcının mevcut konumu (bir geocode), saklı konum listesiyle (yine geocode'lar) eşleştirilir ve haversine mesafesine göre sıralanır
- Teslimat ve sevkiyat: müşterinin adresinin forward geocode'u, sürücü uygulamasına rota oluşturacağı kesin bir koordinat verir
- İlanlar ve envanter: gayrimenkul, tatil kiralama ve otel platformları her ilanı veri girişinde bir kez geocode eder, koordinatı saklar ve "bu bölgede" aramaları için kullanır
- Analitik ve dashboard'lar: gelen kayıtlar (siparişler, destek talepleri, IoT olayları) bölgeye göre toplulaştırılabilsin ya da haritada görselleştirilebilsin diye geocode'lanır
- AI ajanları ve asistanlar: bir LLM'e "yakınımda bir restoran bul" dendiğinde, geocoding adımı kullanıcının konumunu ve aday yerleri koordinatlara çevirir, böylece model mesafe üzerine akıl yürütebilir
Bunların hepsinde geocode, birleştirici anahtardır. Aynı yere ait iki kaydın, adres metinleri "Sokak" mı yoksa "Sk." mi diye anlaşamadığında bile aynı haritada yan yana durmasını sağlayan şey budur.
Üretimdeki Tuzaklar
Geocoding, ilk gün kolay görünen ama her hafta biraz daha zorlaşan bir problemdir.
Adres belirsizliği. "Springfield" 41 ABD eyaletinde bulunur. Ülke, bölge veya posta kodu bağlamı olmadan forward geocode bir yazı tura atışıdır. Elinizde olan tüm bağlamı, ülke kodunu da bias parametresi olarak ekleyerek her zaman gönderin.
Bayatlamış koordinatlar. Sokak numaraları yeniden düzenlenir, mahalle adları değişir, yeni binalar ortaya çıkar. İki yıl önce sakladığınız bir geocode artık aynı binayı göstermiyor olabilir. Tazeliğin önemli olduğu kayıtlar için (teslimat, sevkiyat, regüle sektörler) periyodik olarak yeniden geocode edip saklı koordinatla karşılaştırın.
Hassasiyet aklama. Saf bir UI, hassasiyet locality olduğunda bile geocode sonucunu "✓ Adres bulundu" olarak gösterir. Kullanıcı yeşil tiki görür ve adresin doğrulandığını sanır; oysa API yalnızca şehri eşleştirmiştir. Ödeme veya KYC gibi yüksek riskli akışlarda hassasiyet kademesini her zaman UI'da görünür kılın.
Kota ve hız limitleri. Geocoding API'leri istek başına ücretlendirilir ve saniyede sınırlanır. Toplu işlemler batch'leme, kullanıcıya dönük otomatik tamamlama ise istemci tarafında debounce gerektirir.
Gizlilik. Bir koordinat artı bir zaman damgası kişisel veridir. Geocode'ları diğer her PII gibi davranın: depolamayı kilitleyin, erişimi loglayın ve faaliyet gösterdiğiniz bölgenin GDPR kurallarına uyun.
MapAtlas'ta Geocoding
MapAtlas Geocoding API, forward ve reverse geocoding'i tek bir endpoint'ten işler. Yukarıda sayılan standart alanları (formatlanmış adres, place ID, hassasiyet, güven, sınırlayıcı kutu, adres bileşenleri) döner ve milyonlarca satır işlemesi gereken veri girişi hatları için batch geocoding'i destekler. Ülke ve dil bias parametreleri, her yerel için ayrı istek atmaya gerek bırakmadan sonuçların Avrupa ve global hedef kitleler için alakalı kalmasını sağlar.
Geocoding'i seyahat süresi analiziyle birleştiren iş yükleri için Geocoding API, Isochrone API ve Distance Matrix API ile bir arada çalışır; böylece tek bir adres sorgusu doğrudan "15 dakika içindeki her şeyi göster" veya "bu adayları sürüş süresine göre sırala" akışına bağlanabilir.
Geocode gösterişli değildir. Sadece bir koordinattır. Ama bir metin parçasını, uygulamanın üzerine akıl yürütebileceği bir yere dönüştüren koordinat odur ve o tek veriyi doğru almak, gerçek anlamda konum bilinçli bir özelliği yanlış kıtaya iliştirilmiş bir iğneden ayıran şeydir.
Sıkça Sorulan Sorular
Geocode nedir?
Geocode, genellikle WGS84 datumunda bir enlem ve boylam çiftinden oluşan, yeryüzünde bir yeri tek bir noktaya sabitleyen koordinattır. Çoğu zaman bir adresi geocoding API'sinden geçirmenin sonucudur: API, '10 Downing Street, London' gibi bir metni alır ve 51.5034, -0.1276 gibi koordinatları, eşleşmenin güven düzeyini ve eşleşen yer türünü içeren meta verilerle birlikte döner.
Geocode ile geocoding arasındaki fark nedir?
Geocode çıktıdır (bir koordinat). Geocoding ise onu üreten süreçtir. Forward geocoding bir adresi koordinata çevirir. Ters coğrafi kodlama (reverse geocoding) tam tersini yapar: bir koordinatı alır ve en yakın adresi veya yeri döner. Her ikisi de genellikle aynı API endpoint'i tarafından sunulur.
Bir geocoding API gerçekte ne döner?
İyi bir geocoding API yalnızca enlem ve boylamdan fazlasını döner. Normalleştirilmiş bir adres, eşleşme hassasiyeti (rooftop, sokak, posta kodu, şehir), saklayabileceğiniz bir yer kimliği (place identifier), ülke ve idari bölgeler, eşleşen özelliğin sınırlayıcı kutusu ve bir güven puanı bekleyin. Üretimde sonucun güvenilir olup olmadığına ya da kullanıcıya tekrar sorulup sorulmayacağına karar verirken kullandığınız alanlar precision ve confidence'tır.
Geocode'lar neden adres yerine enlem ve boylam olarak döner?
Koordinatlar belirsizlikten uzak, dilden bağımsız ve makineye uygundur. Adresler ise dağınıktır: yazımları değişir, ülkeden ülkeye format farklıdır ve aynı binanın birkaç geçerli adresi olabilir. Bir koordinat yeryüzündeki bir noktayı birkaç santimetre hassasiyetle benzersiz biçimde tanımlar ve sistemler, veritabanları ve API'ler arasında temiz biçimde taşınır. Çoğu platform koordinatı kaynak gerçek (source of truth) olarak tutar ve gerektiğinde gösterilecek adresi ters coğrafi kodlama ile yeniden türetir.
