Blog · Kurumsal dönüşüm

Kendi il ilçe mahalle veritabanınız mı, API mi?

Kendi il ilçe mahalle veritabanınızı mı tutmalısınız, API mi kullanmalısınız? Bakım yükü, maliyet, entegrasyon süresi ve karar ölçütleri.

12 dk okuma

Adres alanı olan her sistem bir noktada aynı soruya gelir: il ilçe mahalle veritabanını kurum içinde mi tutacaksınız, yoksa bu veriyi bir API'den mi alacaksınız? Soru teknik ekibin işi gibi görünür. Oysa cevabı teslimat başarısını, müşteri hizmetlerine gelen düzeltme taleplerini, satış bölgelerinin doğru atanmasını ve raporların güvenilirliğini doğrudan etkiler. Bu rehberde EKKASOFT Ekibi olarak kararı iş ve operasyon ekiplerinin gözünden ele alıyoruz. Hangi ölçütlere bakmanız gerektiğini, maliyet kalemlerini, geçişi hangi aşamalarla yöneteceğinizi ve sonucun işe yarayıp yaramadığını nasıl anlayacağınızı adım adım anlatıyoruz.

Bu karar neden göründüğünden büyük?

Adres verisi tek bir tablodan ibaret değildir. Aynı il, ilçe ve mahalle bilgisi birçok yerde kullanılır: sipariş formu, fatura kaydı, kargo etiketi, CRM'deki müşteri kartı, satış temsilcisinin bölge listesi ve yönetim raporları. Verinin nereden geldiği ve nasıl güncellendiği, bu süreçlerin hepsinin ortak zeminidir. Kararın göründüğünden büyük olmasının üç nedeni var:

  • Derinlik hızla artar. Katalogda 81 il ve 973 ilçe bulunur; bu iki seviye kısa ve görece durağandır. Hiyerarşi il → ilçe → mahalle → cadde/sokak → dış kapı şeklinde aşağı indikçe kayıt sayısı büyür, değişiklikler sıklaşır. "Bir liste yükleriz, biter" düşüncesi genellikle yalnız ilk iki seviye için geçerlidir.
  • Hatanın bedeli başka ekiplerde ortaya çıkar. Veri eskidiğinde sorunu, veriyi tutan ekip yaşamaz. Sorunu kurye, çağrı merkezi, muhasebe ve satış ekipleri yaşar. Bu yüzden maliyet çoğu zaman görünmez kalır. Zincirleme etkileri Hatalı Adres E-Ticarete Neye Mal Oluyor? yazımızda ele aldık.
  • Geri dönmek pahalıdır. Müşteri kayıtları bir adres yapısına bağlandıktan sonra modeli değiştirmek, mevcut kayıtların yeniden eşlenmesini gerektirir. Kararı baştan bilinçli vermek, sonradan düzeltmekten ucuzdur.

Üç model: kurum içi, API ve hibrit

Tartışma çoğu zaman "kendimiz tutarız" ile "dışarıdan alırız" arasında sıkışır. Pratikte üç model vardır:

  1. Kurum içi veritabanı. Veriyi bir kaynaktan temin eder, kendi sunucularınızda saklar ve güncellemeleri kendiniz yaparsınız. Kendi Türkiye adres veritabanınızın tüm sorumluluğu sizdedir. İçeri aktarma, temizlik, arama altyapısı ve sürüm takibi de bu sorumluluğa dâhildir.
  2. API ile kullanım. Bir adres API kullanırsınız: Veri sağlayıcıda tutulur, sisteminiz ihtiyaç duyduğu anda ilgili listeyi ya da doğrulama sonucunu sorgular. Veriyi güncellemek sağlayıcının işidir. Sizin sorumluluğunuz entegrasyonu yapmak ve referansları doğru saklamaktır.
  3. Hibrit model. API'yi güncel kaynak kabul eder, sık kullanılan listeleri önbellekte ya da yerel bir kopyada tutarsınız. Toplu snapshot dosyaları, yerel kopyayı belirli aralıklarla yenilemenin bir yoludur.

Burada önemli bir ayrım var: Bir il ilçe mahalle veritabanını kendiniz tutmak, çoğu zaman veriyi sıfırdan derlemek anlamına gelmez. Bir dosyayı içeri alıp sonra yaşatmak anlamına gelir. Asıl iş yükü ilk yüklemede değildir. Asıl yük, sonraki aylarda ve yıllarda o veriyi güncel tutmaktır.

Karar çerçevesi: beş ölçüt

Aşağıdaki beş ölçüt, karar toplantısında masaya konması gereken başlıklardır. İlk üçü en çok tartışılanlardır; son ikisi sıkça unutulur.

ÖlçütKurum içi veritabanıAPI ile kullanım
Güncelleme ve bakımTamamen sizdeSağlayıcıda; siz sürüm değişimini izlersiniz
Altyapı ve ekipSunucu, arama altyapısı, kalıcı ekip zamanıPaket bedeli, entegrasyon ve izleme zamanı
Entegrasyon süresiVeri hazırlığı ve güncelleme süreci dâhil uzunHazır uçlarla daha kısa; göç işi iki modelde de var
Kontrol ve bağımlılıkVeri tamamen sizdeDış servise bağımlılık; önbellek ve yedek akışla yönetilir
Kapsam derinliğiDerinlik arttıkça yük ağırlaşırSokak, dış kapı ve doğrulama hazır uçlarla gelir

Güncelleme ve bakım yükü

Adres verisi durağan değildir: Mahalle adları değişebilir, yeni sokaklar açılır, binalar eklenir, bazı kayıtlar kullanımdan kalkar. Kurum içinde tutulan bir il ilçe mahalle veritabanında her değişiklik sizin iş listenize düşer:

  • Kaynağı takip etmek ve yeni veriyi zamanında temin etmek
  • Eski ve yeni veri arasındaki farkları çıkarmak
  • Değişen kayıtlara bağlı müşteri adreslerini yeniden eşlemek
  • Güncellemeyi test etmek ve canlıya almak
  • Süreci belgeleyip bir sonraki sefer için tekrarlanabilir kılmak

Bakım maliyeti bu yüzden sinsi bir kalemdir: Kimsenin iş tanımında açıkça yazmaz ve bütçede ayrı bir satır olarak görünmez. Çoğu zaman da ancak bu işi bilen tek kişi ekipten ayrıldığında fark edilir. Güncelleme ertelendiğinde veri sessizce eskir. Sorun, kurye bir sokağı bulamadığında ya da müşteri formda kendi mahallesini göremediğinde ortaya çıkar.

API modelinde bakım ortadan kalkmaz, biçim değiştirir. Veriyi güncellemek sağlayıcının işidir; sizin işiniz değişikliğin sisteminize düzgün yansımasını sağlamaktır. API Türkiye'de katalog sürümlü veri setleri hâlinde yayımlanır ve her kayıt sürümden bağımsız, kalıcı bir kimlik (stableId) taşır. Müşteri adreslerini bu kimlikle saklayabilirsiniz. Böylece katalog yeni bir sürüme geçtiğinde kayıtları adlara göre yeniden eşlemeniz gerekmez; kalıcı referansı kullanırsınız. Adresin neden metin olarak değil de kimlikle saklanması gerektiğini Adres Veritabanı Tasarımı: Metin Değil, Kalıcı Kimlik yazısında anlattık.

Altyapı ve ekip maliyeti

Maliyeti doğru karşılaştırmak için yalnız ilk kurulumu hesaba katmak yetmez. Birkaç yıllık toplam sahip olma maliyetine bakmalısınız. İlk yıl kurum içi model ucuz görünebilir, çünkü bakım kalemleri henüz birikmemiştir.

Maliyet kalemiKurum içi veritabanıAPI ile kullanım
Veri teminiEdinim ve güncel sürümlerin takibiPaket kapsamında
AltyapıSunucu, yedekleme, sokak ve dış kapı ölçeğinde depolamaHafif bir önbellek katmanı
AramaTürkçe karakter ve yazım hatasına toleranslı aramayı geliştirmekHazır akıllı arama
Ekip zamanıKalıcı bakım, test, sürüm geçişiBir kerelik entegrasyon ve sürekli izleme
Süreklilik riskiBilginin bir iki kişide toplanmasıDış servise bağımlılık

İki kalem sıkça gözden kaçar. Birincisi arama altyapısı: Kullanıcı "Bağdat Cadessi" ya da "kadikoy" yazdığında doğru öneriyi göstermek, bir listeyi veritabanına yüklemekten çok daha fazla emek ister. İkincisi fırsat maliyeti: Adres verisini yaşatmaya ayrılan her geliştirici saati, ürününüzün asıl farkını yaratan işlerden çekilmiş bir saattir.

API modelinde maliyet daha öngörülebilirdir ama sıfır değildir. Paket bedeli, kullanım hacminize ve ihtiyaç duyduğunuz özelliklere göre değişir. Seçenekleri paket karşılaştırması bölümünde inceleyebilirsiniz. Buna entegrasyon için gereken geliştirici zamanını da eklemelisiniz. Hata, kota ve servis durumunu izleme işi de bu hesaba girer.

Entegrasyon süresi

Burada iki soruyu birbirinden ayırmak gerekir: "İlk sonucu ne zaman görürüz?" ve "Sistem ne zaman gerçekten hazır olur?"

Kurum içi modelde yol şöyledir: veri temini, şema tasarımı, içeri aktarma, veri temizliği, arama geliştirme, formlara bağlama, test ve düzenli güncelleme sürecinin kurulması. Son adım çoğu planda yer almaz. Oysa sistemin uzun vadede ayakta kalması ona bağlıdır.

API modelinde yol daha kısadır: API anahtarı almak, sunucu tarafında ilgili uçları çağırmak, formu bu listelere bağlamak, hata ve kota durumlarını ele almak, test etmek. Hazır adres seçici bileşen örnekleri form tarafındaki işi ayrıca kısaltabilir. Teknik ekibinizle konuşurken somut bir örnek verelim: İstanbul'un ilçelerini getiren istek tek satırdır. Buradaki 34, İstanbul'un plaka koduyla aynı olan il kodudur.

curl "https://api.apiturkiye.com/v1/provinces/34/districts" -H "X-API-Key: apt_live_..."

Bu istek sunucu tarafından yapılır; API anahtarı tarayıcıda çalışan koda ya da mobil uygulamaya konmaz.

İki modelde de süreyi uzatan ortak bir iş vardır: mevcut müşteri adreslerinin yeni yapıya eşlenmesi. Yıllar içinde serbest metinle girilmiş adresleri kalıcı kimliklere bağlamak gerekir. Hangi modeli seçerseniz seçin, bu iş ayrıca planlanması gereken bir aşamadır.

Kontrol ve bağımlılık

Kurum içi modelin en güçlü yanı kontroldür: Veri tamamen sizin ortamınızdadır ve dış bir servise erişim gerektirmez. Kapalı ağda çalışan sistemler için bu belirleyici olabilir. Veri konumu konusunda katı iç politikaları olan kurumlar için de durum aynıdır.

API modelinde ise dış servise bağımlılığı yönetmeniz gerekir. İyi bir başlangıç için şu önlemleri alabilirsiniz:

  • Sık kullanılan il ve ilçe listelerini önbellekte tutun.
  • İstekler için zaman aşımı belirleyin.
  • Servis yanıt vermediğinde formun nasıl davranacağına önceden karar verin.
  • Servis durumu sayfasını izleme akışınıza ekleyin.

Kişisel veri açısından bir not: Adres kataloğu kendi başına kimseye ait değildir; ancak doğrulama için gönderdiğiniz adres bileşenleri bir müşteriye ait olabilir. Veri işleme ve aktarım süreçlerinizi KVKK dâhil ilgili mevzuat açısından değerlendirmenizi öneririz. Bu değerlendirmeyi hukuk ekibinizle ya da bir uzmanla yapın.

Kapsam derinliği

Hangi seviyeye kadar veri gerektiğini netleştirmek, kararın yarısıdır. Yalnız il ve ilçe soran bir başvuru formu ile kapı numarasına kadar kontrol yapan bir teslimat süreci aynı ihtiyaç değildir. Derinlik arttıkça kurum içi modelin yükü büyür. API Türkiye'de tam adres kataloğu ve akıllı arama ücretsiz Core paketinde yer alır. Adres doğrulama ve standartlaştırma ise Pro ve üzeri paketlerde sunulur.

Kendi il ilçe mahalle veritabanınız ne zaman mantıklı?

Her iki modelin de doğru seçim olduğu durumlar vardır. Karar toplantısını hızlandırmak için önce şu üç soruyu yanıtlayın:

  1. Hangi derinliğe ihtiyacımız var? Yalnız il ve ilçe mi, yoksa mahalle, sokak ve dış kapı da mı?
  2. Güncellemeyi kim yapacak? Bu işi üstlenecek kişinin ya da ekibin adını bugün yazabiliyor musunuz?
  3. Veri erişilemezse ne olur? Sipariş alma durur mu, yoksa süreç kontrollü bir yedek akışla devam edebilir mi?

İkinci soruya net bir isim veremiyorsanız kurum içi model fiilen sahipsiz bir veritabanı anlamına gelir. Aşağıdaki tablo yaygın senaryolar için bir başlangıç noktasıdır:

SenaryoMantıklı modelGerekçe
Yalnız il ve ilçe seçilen, düşük hacimli bir formKurum içi liste veya APIİlk iki seviye görece durağandır; yine de periyodik kontrol gerekir
E-ticarette mahalle ve sokak düzeyinde teslimat adresiAPIDerinlik ve güncellik ihtiyacı yüksektir; arama ve doğrulama hazır gelir
Lojistik ve saha operasyonunda yüksek hacimli toplu işlerHibritYerel kopya toplu işleri kolaylaştırır; API güncel kaynak olarak kalır
CRM ve satışta kayıt temizliği ve bölge atamasıAPI ve doğrulamaKayıtlar kalıcı kimliklere bağlanır, raporlar tek formatta birleşir
Dış servise erişimi olmayan kapalı ağKurum içi veya snapshot tabanlı hibritErişim kısıtı belirleyicidir; bakım sorumluluğu netleşmelidir
Adres verisini kendisi üreten ya da zenginleştiren kurumKurum içiVeri çekirdek işin parçasıdır; bakım zaten ekibin uzmanlık alanıdır

Hibrit model, özellikle yüksek hacimli ekipler için dengeli bir yoldur. API Türkiye'de toplu snapshot dosyaları Ultra paketinde sunulur. Her dosya için bir sağlama toplamı (checksum) yayımlanır; böylece indirilen dosyanın eksiksiz ve değişmeden geldiğini kontrol edebilirsiniz. Kota, hız ve operasyon modelinin kuruma özel belirlenmesi gereken durumlar için Enterprise seçeneği vardır.

Aşamalı uygulama planı

Aşağıdaki plan, API veya hibrit modele geçişi esas alır. Kurum içi modeli seçtiyseniz aşamalar benzerdir; yalnız pilotun yerini veri hazırlığı alır.

1. Keşif ve ihtiyaç analizi

  • Roller: Operasyon lideri, ürün sahibi, bir teknik temsilci.
  • Girdiler: Adres kullanan süreçlerin listesi, mevcut adres kayıtlarından örnekler, adres kaynaklı şikâyet ve düzeltme talepleri.
  • Çıktı: Bir ihtiyaç belgesi. Bu belge gereken derinliği, yaklaşık kullanım hacmini, doğrulama ve çevrim dışı çalışma ihtiyacını tanımlar.

2. Karar ve maliyet karşılaştırması

  • Roller: Finans veya satın alma, teknik lider, operasyon lideri.
  • Girdiler: İhtiyaç belgesi, paket bilgileri, iç ekip kapasitesi.
  • Çıktı: Seçilen model, birkaç yıllık toplam sahip olma maliyeti karşılaştırması ve bir sorumluluk matrisi. Matris şu soruları yanıtlar: Verinin sahibi kim? Değişiklikleri kim izler? Sorun çıktığında kime gidilir?

3. Pilot

  • Roller: Geliştirici, test sorumlusu, operasyon temsilcisi.
  • Girdiler: API anahtarı, API dokümantasyonu, pilot için seçilmiş tek bir form ya da kanal.
  • Çıktı: Çalışan pilot ve ilk gözlemler. Hata, kota ve erişim sorunlarında sistemin nasıl davranacağı da bu aşamada kararlaştırılır.

Pilotta yalnız liste ve arama kullanacaksanız ücretsiz Core paketiyle başlayabilirsiniz; doğrulamayı da denemek için Pro ve üzeri bir paket gerekir.

4. Mevcut verinin eşlenmesi

  • Roller: Veri sorumlusu, operasyon ekibi, gerektiğinde müşteri hizmetleri.
  • Girdiler: Mevcut müşteri adresleri.
  • Çıktı: Kalıcı kimliklerle eşleşmiş kayıtlar ve eşleşmeyenler için bir düzeltme kuyruğu.

Bu aşamada adres doğrulama işinizi kolaylaştırır. Eşleşme kurulamadığında yanıt, adresin hangi seviyede koptuğunu gösterir: il, ilçe, mahalle, sokak ya da kapı numarası. Varsa aynı üst kapsamdaki adayları da listeler. Operasyon ekibi kuyruğu bu bilgiyle önceliklendirebilir. Başarılı doğrulamada dönen veri seti sürümünü kayıtla birlikte saklamanızı öneririz. Böylece ileride "Bu adres hangi veriyle doğrulandı?" sorusunu yanıtlayabilirsiniz.

5. Yaygınlaştırma

  • Roller: Ürün sahibi, kanal sorumluları.
  • Girdiler: Pilot sonuçları, kanal listesi (web, mobil, pazaryeri, çağrı merkezi, CRM).
  • Çıktı: Tüm kanallarda aynı adres yapısı ve aynı kimlik alanları.

6. İşletme ve sürekli iyileştirme

  • Roller: İsimle belirlenmiş bir sistem sahibi, teknik destek sorumlusu.
  • Girdiler: İzleme panoları, hata kayıtları, kullanım verileri.
  • Çıktı: Düzenli gözden geçirme notları, paket ve kapasite kararları, iyileştirme listesi.

Sık yapılan hatalar, riskler ve önlemler

Hata veya riskSonucuÖnlem
Adresi yalnız metin olarak saklamakAynı adres farklı yazımlarla çoğalır, raporlar bölünürSeçilen her seviyenin kalıcı kimliğini saklayın
Kayıtları adlarına göre birleştirmekFarklı yerleşimlerdeki aynı adlı mahalleler karışırEşleştirmede kimlik kullanın; seçim listesinde gerekirse bağlı yerleşimin adını etikete ekleyin
Bir kez yükleyip unutmakVeri sessizce eskirGüncelleme ve sürüm takibi için isimle sorumlu atayın
Kayıt sayısını kalite ölçütü saymakSağlayıcılar yanlış karşılaştırılırKayıtların neyi kapsadığını sorun. Katalogdaki mahalle kayıtları köy ve belde bağlamını da içerir; bu yüzden başka kaynaklardaki mahalle sayılarıyla doğrudan karşılaştırılamaz
Arama önerisini doğrulama yerine koymakEksik ya da geçersiz adresler sisteme girerÖneri sıralaması adresin geçerli olduğunu kanıtlamaz; kritik süreçlerde doğrulama kullanın
API anahtarını tarayıcı veya mobil koda koymakAnahtar yetkisiz kişilerin eline geçebilirİstekleri sunucudan yapın; anahtarı loglara ve kod deposuna yazmayın
Kota ve hız sınırını planlamamakYoğun dönemde istekler reddedilirSabit listeleri önbelleğe alın, kullanım trendini izleyin
Eşleştirme işini küçümsemekProje takvimi kayarGöçü ayrı bir aşama olarak planlayın, düzeltme kuyruğuna kaynak ayırın

Son bir öneri: Teknik ekibinizden, hata durumlarında mesaj metnine değil hata koduna göre karar vermesini isteyin. Örneğin kota dolduğunda sistem aynı isteği sürekli tekrarlamamalı, yenilenme zamanını beklemelidir. Bu tür kurallar operasyon tarafındaki sürprizleri azaltır.

Başarıyı nasıl ölçersiniz?

Ölçüme başlamadan önce mevcut durumu bir referans dönem için kaydedin. Her göstergeyi aynı tanımla ve düzenli aralıklarla izleyin. Mutlak değerlerden çok yöne odaklanın: Gösterge doğru yöne gidiyor mu?

Operasyon

  • Adres kaynaklı teslim edilemeyen ve geri dönen gönderilerin seyri
  • Müşteri hizmetlerine gelen adres düzeltme talepleri
  • Kurye ya da saha ekibinden gelen "adres bulunamadı" bildirimleri

Müşteri deneyimi

  • Ödeme akışında adres adımında yaşanan terk
  • Adres girişine harcanan süre
  • Manuel adres girişi seçeneğinin kullanılma sıklığı

Veri kalitesi

  • Kalıcı kimlikle eşleşmiş kayıtların toplam içindeki payının gelişimi
  • Düzeltme kuyruğunun büyüklüğü ve kayıtların kuyrukta bekleme süresi
  • Raporlarda aynı ilçe ya da mahallenin farklı yazımlarla bölünüp bölünmediği

Teknik ve maliyet

  • Hata yanıtlarının koda göre dağılımı ve kota kullanımının seyri
  • Adres verisinin bakımına harcanan ekip zamanı
  • Planlanan ve gerçekleşen toplam sahip olma maliyeti

Bu göstergeleri operasyon ve teknik ekibin birlikte katıldığı düzenli bir toplantıda gözden geçirin. Böylece bir sorunun süreçten mi yoksa sistemden mi kaynaklandığını hızla ayırt edebilirsiniz.

Karar ve uygulama kontrol listesi

Karar öncesi

  • Adres kullanan tüm süreçler listelendi.
  • Gereken derinlik (il, ilçe, mahalle, sokak, dış kapı) belirlendi.
  • Doğrulamanın hangi süreçlerde gerektiği netleşti.
  • Güncelleme ve sürüm takibinin sorumlusu isimle atandı.
  • Birkaç yıllık toplam sahip olma maliyeti karşılaştırıldı.
  • Dış servise erişilemediğinde iş akışının nasıl süreceğine karar verildi.
  • Kişisel veri boyutu hukuk ekibiyle değerlendirildi.

Entegrasyon sırasında

  • Veri modeli adresleri kalıcı kimlikle saklıyor.
  • API anahtarı yalnız sunucu tarafında kullanılıyor.
  • Sabit listeler önbelleğe alınıyor.
  • Hata, kota ve erişim sorunları için davranış tanımlı.
  • Mevcut kayıtların eşleştirme planı ve düzeltme kuyruğu hazır.

İşletme döneminde

  • Referans değerler kaydedildi, göstergeler düzenli izleniyor.
  • Veri seti sürüm değişiklikleri takip ediliyor.
  • Servis durumu izleme akışına eklendi.
  • Paket ve kapasite ihtiyacı belirli aralıklarla yeniden değerlendiriliyor.

Sonraki adım

Kendi il ilçe mahalle veritabanınızı mı kuracağınıza, yoksa API mi kullanacağınıza karar vermenin sağlıklı yolu, varsayımları küçük bir pilotla sınamaktır. Ücretsiz kayıt sayfasından hesap oluşturup tek bir formda il, ilçe ve mahalle listelerini deneyebilirsiniz. Uç ve parametre ayrıntıları için teknik ekibinizi API dokümantasyonuna yönlendirin. Ürünün genel kapsamını Türkiye adres API'si sayfasında, paket seçeneklerini fiyatlar bölümünde bulabilirsiniz. Kurumunuza özel bir operasyon modeline ihtiyaç duyuyorsanız [email protected] adresinden bize ulaşabilirsiniz.