Wiki

Tapusor Veri API'si

Tapusor Veri API'si, Türkiye gayrimenkul piyasasına dair dağınık veri kaynaklarını (TKGM kadastrosu, imar planları, risk katmanları, piyasa istatistikleri, resmî kayıtlar) tek bir programlama arayüzünde (API) birleştiren, kullanım başına ücretlendirilen bir veri hizmetidir. Bir yazılım, bir koordinat ya da bir parsel kimliği göndererek bu verilerin hazır, standart biçimde işlenmiş hâlini alır.

Bu sayfa — wiki — API'yi kavram kavram anlatır: ne işe yaradığı, nasıl çalıştığı, kategorilerin neyi kapsadığı ve sık kullanılan terimlerin anlamı. Belirli bir uç noktanın tüm parametrelerini ve çalışan bir örneğini görmek için belge sayfasına, yöneticilere kısa bir tanıtım yapmak için sunuma bakın.

Kimler kullanır?

Nasıl çalışır

Tapusor Veri API'si bir REST API'dir: her hizmet kendi internet adresine (URL) sahiptir, istek düz HTTP GET ile gönderilir, yanıt JSON (ya da seçime göre GeoJSON / düz metin) olarak döner. Sunucuya bağlanmak, oturum açmak ya da özel bir kütüphane kurmak gerekmez — herhangi bir programlama dilinden, hatta tarayıcının adres satırından bile istek gönderilebilir.

Bir isteğin yolculuğu

1. İstemci (sizin yazılımınız) bir adrese istek gönderir, anahtarını Authorization başlığında taşır.
2. Kapı anahtarı doğrular, hesabınızın planını, kalan kredisini ve dakikalık hız sınırını kontrol eder.
3. Gönderdiğiniz parametreler (koordinat, kategori kodu, tarih aralığı…) denetlenir; geçersizse istek hiç işlenmeden, ücretsiz olarak reddedilir.
4. İlgili veritabanı sorgulanır, sonuç işlenir ve standart bir yanıt gövdesine (data + meta) yerleştirilir.
5. Yanıt size döner; kredi yalnız bu adımda, yanıt başarılı ve veri doluysa düşer.

# en basit örnek: bir koordinatın bileşik risk puanı
curl "https://www.ai.tapusor.com/public/api/v1/risk/score?lat=41.0369&lng=28.985" \
  -H "Authorization: Bearer $TAPUSOR_API_KEY"

Yanıtın yapısı

Başarılı her yanıt iki ana alan taşır: data (istediğiniz sonuç) ve meta (bu isteğe dair bilgi: istek numarası, düşen kredi, kalan kredi, sürüm, geçen süre). Hata yanıtları ise tek bir error nesnesi içinde makine tarafından okunabilir bir code ve insan diliyle bir message taşır — ayrıntısı için Hata yönetimi sayfasına bakın.

Kimlik ve güvenlik

Her istek bir API anahtarı ile kimliklendirilir. Anahtar, Authorization: Bearer <anahtar> ya da X-API-Key: <anahtar> başlığıyla gönderilir; adres satırına yazılmaz (adres satırları günlük dosyalarında ve tarayıcı geçmişinde saklanabilir).

Anahtarın kendisi sistemde saklanmaz — yalnız tek yönlü (geri döndürülemez) özeti tutulur. Bu yüzden oluşturulduğu anda bir kez gösterilir; o anda kaydedilmezse yenisi istenmesi gerekir, eskisi iptal edilir.

Alınan önlemler

• Bağlantı yalnız şifrelidir (HTTPS); şifresiz istek kabul edilmez.
• Anahtar isterseniz belirli IP adreslerine ya da ağlara kilitlenebilir.
• Hem anahtar başına hem IP adresi başına dakikalık istek sınırı vardır; aşımlar günlüğe kaydedilir.
• Yanlış anahtar denemeleri yavaşlatılır (kaba kuvvet denemesini zorlaştırmak için).
• Yanıtlarda sunucu yazılımı ve iç adresler gizlenir.

Çıktı biçimleri

Her veri ucu, adrese eklenen format parametresiyle üç farklı biçimde yanıt verebilir. Kredi ve sınırlar biçimden bağımsız, aynıdır.

curl -s "https://www.ai.tapusor.com/public/api/v1/market/hexagons?bbox=28.74,41.03,28.78,41.06&resolution=4&format=geojson" \
  -H "Authorization: Bearer $TAPUSOR_API_KEY" > hexagonlar.geojson

Hata yönetimi

Bir istek başarısız olduğunda yanıt gövdesi her zaman aynı biçimdedir ve HTTP durum koduyla birlikte gelir. Hatalı isteklerden kredi düşmez.

{ "error": { "code": "invalid_parameter", "message": "lat: aralık dışı (35.5–42.5)", "param": "lat", "request_id": "req_…" } }

code alanı yazılımınızın karar vermesi için sabit bir metindir (asla değişmez); message ise okunması için Türkçedir. Sorun bildirirken request_id değerini paylaşmanız teşhisi hızlandırır.

Krediler ve faturalama

Her hizmetin sabit bir kredi maliyeti vardır (katalogda, her hizmetin yanında yazar — bkz. kategori sayfaları). Planınız aylık bir kredi kotası içerir; kota ayın belirlediğiniz bir gününde yenilenir ve kullanılmayan kredi bir sonraki döneme devretmez.

Aşım nasıl işler?

Planınızda aşım açıksa, kota bittiğinde istekler durmaz; fazladan kullanılan her 1.000 kredi, dönem sonunda sabit bir ücretle faturalanır. Aşım kapalıysa, kota bitince yeni istekler quota_exceeded hatasıyla geri çevrilir; yeni dönem başlayana kadar beklenir.

Fiyatlara KDV dahil değildir. Kurumsal sözleşme için bizimle görüşün.

Anlık kullanımınızı ve dönem sonu tahmini faturanızı sorgulamak için ücretsiz GET /public/api/v1/usage ucunu kullanabilirsiniz.

Konum ve kadastro

Bir koordinat ya da bir ada/parsel kimliği verdiğinizde, o yerin resmî kadastro kaydını, idari (il/ilçe/mahalle) ve TKGM kimliklerini, sınır geometrisini döner. Hemen her diğer kategorinin temelidir: bir risk ya da piyasa sorgusu için önce burada "nerede olduğunuzu" netleştirirsiniz.

İmar ve risk

Bir parselin üzerinde ne inşa edilebileceğini (imar fonksiyonu, plan tadilatları), zemin ve heyelan riskini, varsa mevcut bina bilgisini ve parselin açık cephelerini döner. Değerleme ve geliştirme kararlarında kritik bir ön filtredir.

Piyasa verisi

Satılık ve kiralık ilan verilerinden türetilen, hexagon / ilçe / mahalle düzeyinde medyan m² değeri, kira getirisi, çeyreklik trend, pazarda kalma süresi ve resmî TKGM satış adetlerini kapsar. Veriler kişiye özel değil; toplulaştırılmış ve tekilleştirilmiştir.

Örnek sonuç

Değerleme

Bir parselin ya da bir bağımsız bölümün (daire, dükkân…) tahmini piyasa değerini hesaplar. Model, yakın ve güncel emsal ilanları mesafe × ilan yaşına göre ağırlıklandırır; sonuçla birlikte bir değer aralığı ve 0–100 arası bir güven puanı döner. Emsal ilanların kendisi asla dönmez — yalnız sonuç.

Örnek sonuç

Yukarıdaki örnek, İstanbul Küçükçekmece / Atakent'te 100 m² bir satılık daire için alınmış gerçek bir API yanıtıdır. confidence.components alanı puanı dört bileşene ayırır: örnek (yeterli emsal var mı), yakınlık (emsaller ne kadar yakın), tutarlılık (emsaller arasında ne kadar uyum var) ve uyum (konu taşınmazla ne kadar benzer).

Resmî kayıtlar

Resmî Gazete kararlarını (sit, kamulaştırma, kentsel dönüşüm ilanları dahil), Yargıtay kararlarını ve icra / ihale ilanlarını; bölgeye, tarihe ve metne göre aranabilir, konuma bağlı hâlde sunar.

Çevre ve erişim

Bir noktanın çevresindeki donatıları (ulaşım, eğitim, sağlık, alışveriş…), bölgedeki toplam donatı dağılımını, yakın tapu satışlarını, platformdaki talep yoğunluğunu ve ham veri katmanlarını (imar planı, POI, haber/şikâyet) kapsar.

Bölge analizi

Bir merkez nokta etrafında, artan yarıçaplı halkalar (örn. 500 m / 1.000 m / 2.000 m) içinde nüfus, ilan yoğunluğu ya da tapu satışı gibi göstergeleri toplayan "etki alanı" (catchment) analizidir; bir yatırımın çekim gücünü ölçmek için kullanılır.

Teknik analiz ve risk

Tek bir fonksiyonun ürettiği 70'in üzerinde bağımsız kontrolü — her biri kendi adresinde — ve bunların ağırlıklı toplamından oluşan bileşik bir risk puanını kapsar. Yalnız ihtiyacınız olan kontrolü çağırıp yalnız onu ödersiniz.

Ayrıca tüm kontrollerin ağırlıklı toplamını tek puanda veren risk.score, bir parseldeki ilanların teknik özetini veren technical.summary, seçtiğiniz kontrolleri tek istekte çalıştıran technical.controls ve yarıçap içindeki haber / şikâyet yoğunluğunu veren news.summary hizmetleri de bu kategoridedir:

Aşağıdaki 71 kontrolün her biri, technical.controls'dan bağımsız olarak, kendi adresinde de çağrılabilir — yalnız ihtiyacınız olanı ödersiniz:

Kritik risk ve yasal durum (11 kontrol)

İmar hakları (10 kontrol)

Tarım ve doğal kullanım (4 kontrol)

Altyapı ve stratejik konum (4 kontrol)

Fiziksel ve mekânsal özellikler (6 kontrol)

Lokasyon erişimi (20 kontrol)

Değer ve satış analitiği (9 kontrol)

Destekleyici veriler (7 kontrol)

WMS harita servisi

WMS (Web Map Service), coğrafi verileri hazır harita görüntüsü (resim) olarak sunan, uluslararası standart (OGC) bir protokoldür. Veri API'sinin WMS servisi, risk ve kadastro katmanlarını bu biçimde sunar; QGIS, ArcGIS, MapInfo gibi masaüstü CBS yazılımları ile Leaflet, OpenLayers gibi web harita kütüphaneleri, tek bir adres girerek bu katmanları doğrudan kendi haritalarına katman olarak ekleyebilir — ayrı bir programlama gerekmez.

Bir CBS programına bağlanmak için yalnız adres ve anahtar yeterlidir; program katman listesini (GetCapabilities) kendisi otomatik indirir.

QGIS: Katman › Katman Ekle › WMS/WMTS › Yeni bağlantı
  URL: https://www.ai.tapusor.com/public/api/v1/wms
  HTTP başlığı: X-API-Key = tsk_live_…      (desteklenmiyorsa: https://www.ai.tapusor.com/public/api/v1/wms?key=tsk_live_…)

Katmanlar

Terimler sözlüğü

API anahtarı

İsteklerinizi kimliklendiren, sizi tanımlayan gizli metin. tsk_live_… (ücretli) ya da tsk_test_… (ücretsiz deneme) ile başlar.

Kredi

Her hizmetin sabit bir maliyeti olan, planınızın aylık kotasından düşen birim. Yalnız başarılı ve veri döndüren isteklerde düşer.

Hız sınırı (rate limit)

Bir anahtarın (ya da bir IP adresinin) dakikada atabileceği en çok istek sayısı; aşılırsa 429 hatası ve ne zaman tekrar deneyebileceğinizi söyleyen bir süre (Retry-After) döner.

TKGM

Tapu ve Kadastro Genel Müdürlüğü. Kadastroya ilişkin "resmî" kimlik ve sınırların kaynağıdır (il/ilçe/mahalle kimlikleri, parsel kayıtları).

İdari (plaka) kodu / TKGM kodu

Türkiye'de iki ayrı il numaralandırması vardır. Günlük hayattaki plaka kodu "idari" kod olarak geçer (İstanbul = 34); TKGM'nin kendi sistemi farklı bir numara kullanır (İstanbul = 56). Bu API'de province gibi parametreler idari (plaka) kodu kullanır; /v1/locations ve ada/parsel araması ise TKGM kimliklerini kullanır.

Hexagon

Haritayı altıgen hücrelere bölen, piyasa istatistiklerinin toplulaştırıldığı birim. Çözünürlük 2 (çok iri) ile 7 (çok ince) arasında seçilir.

Alt kategori (subcategory)

İlanın türünü belirten sayısal kod — örn. 10010 satılık konut dairesi, 10176 kiralık konut dairesi. Tam liste GET /v1/products yanıtında yer alır.

Çeyrek (quarter)

YYYYQ biçiminde bir zaman birimi — örn. 20262, 2026'nın 2. çeyreği (nisan–haziran). Piyasa verileri çoğunlukla çeyreklik toplulaştırılır.

GeoJSON

Coğrafi verileri (nokta, çizgi, çokgen) taşıyan, yaygın kullanılan açık bir JSON biçimi; çoğu harita yazılımı doğrudan okur.

WMS / OGC

Web Map Service: coğrafi katmanları hazır resim olarak sunan açık standart. OGC (Open Geospatial Consortium), bu ve benzer standartları belirleyen uluslararası kuruluştur.

Güven puanı (confidence score)

Otomatik değerleme sonucunun ne kadar güvenilir olduğunu gösteren, 0–100 arası bir puan; kullanılan emsal sayısına, yakınlığına ve tutarlılığına göre hesaplanır.

Aşım (overage)

Planınızın aylık kredi kotasını aştığınızda devam eden kullanım; açıksa dönem sonunda ek ücretle faturalanır, kapalıysa istekler durur.

Sık sorulan sorular

Sürüm geçmişi

Yol öneki (/v1) bir sürüm sözüdür: içinde var olan bir alan silinmez ya da anlamı değiştirilmez, yalnız yeni alan ve hizmet eklenir.

• 22 Ekim 2026 · 1.0.0İlk yayın: konum, imar, piyasa, değerleme ve bölge analizi kategorilerinde ilk hizmet seti.
• 22 Ekim 2026 · 1.1.0Resmî kayıtlar (Resmî Gazete, Yargıtay, icra/ihale), teknik analiz, çevre ve erişim hizmetleri eklendi: 23 hizmetten 38 hizmete çıkıldı.
• 23 Ekim 2026 · 1.2.0Değerleme ve piyasa hizmetlerine oda sayısı süzgeci eklendi; belgeye her hizmet için gerçek örnek yanıtlar kondu.
• 23 Ekim 2026 · 1.3.071 teknik kontrolün her biri kendi adresine ayrıldı: katalog 38'den 109 hizmete çıktı.
• 23 Ekim 2026 · 1.4.0Çıktı biçimi seçimi eklendi: format=json|geojson|text.
• 23 Ekim 2026 · 1.4.0WMS harita servisi yayına alındı: 20 katman, OGC standardı.
• 23 Ekim 2026Bu wiki sayfası, tanıtım sunumu ve "API'ye sorun" yapay zekâ asistanı eklendi.