Veri seti

API

Hook'un arkasındaki veri paketin içinde gelir ve @virastack/address/data girişinden React olmadan kullanılabilir:

import {
  districts,
  findPostalCode,
  neighbourhoods,
  province,
  provinces,
  source,
} from "@virastack/address/data"
 
provinces.length        // 81
province(34)?.name      // "İSTANBUL"
districts(34)           // ["ADALAR", "ARNAVUTKÖY", ...]
 
const byDistrict = await neighbourhoods(34)
byDistrict.get("FATİH")
// [{ name: "AKSARAY MAH.", postalCode: "34096", ... }, ...]
 
source.date             // "2026-10-28": verinin toplandığı gün
source.neighbourhoods   // 72466
 
await findPostalCode("34710")
// { postalCode: "34710", province: { code: 34, ... },
//   district: "KADIKÖY", neighbourhoods: [{ name: "CAFERAĞA MAH.", ... }] }

provinces, province ve districts eşzamanlıdır. neighbourhoods(code) bir Promise döndürür ve sonucu önbelleğe alır: aynı anda gelen iki istek tek yüklemeyi paylaşır, başarısız bir yükleme hatırlanmaz ve il yeniden istenince tekrar denenir. İl olmayan bir kod boş bir Map verir.

Mahallelerin çoğunun tek posta kodu vardır. Birkaç yüzünün birden fazla, en çok sekiz posta kodu vardır ve hepsi korunur: postalCodes tam cevaptır, postalCode yaygın durum için ilkidir.

findPostalCode(code) bir posta kodunun ilini, ilçesini ve kapsadığı mahalleleri verir; veri setinde yoksa null. Yalnızca kodun ilk iki hanesindeki il yüklenir. Her kod tek bir ilçeye aittir ve ilin plaka koduyla başlar; veri derlenirken bu kontrol edilir.

Ne kadar indirir?

Sayfa açılınca il ve ilçe adları gelir; bir il seçilince yalnızca o ilin mahalleleri indirilir. Bunun için ayar gerekmez: her il ayrı bir dosyadır ve projenizin bundler'ı onu kendiliğinden ayırır. Sunucuda da yalnızca istenen iller belleğe alınır.

Tablodaki boyutlar, tarayıcının ağdan gerçekten indirdiği sıkıştırılmış (gzip) hâlidir.

81 ilin 75'i 10 kB'ın altındadır. Tipik bir ziyaret, il ve ilçe adlarıyla seçilen ili birlikte yaklaşık 10 kB indirir. İstanbul ve Ankara gibi büyük şehirlerin dosyası da 10 kB'ın altındadır; en büyük dosyalar binlerce köyü olan kırsal illerindir. Veri derlemesi en büyük il 30 kB'ı geçerse başarısız olur; bir güncelleme yükü sessizce büyütemez.

Kendi loader'ınız

Mahalleleri diskten, bir CDN'den ya da kendi endpoint'inizden okumak için loader değiştirin:

import { setLoader } from "@virastack/address/data"
 
setLoader(async (provinceCode) => {
  const response = await fetch(`/api/address/${provinceCode}`)
  return response.text()
})
 
setLoader(null) // paketteki modüllere dön

Loader ilin kodlanmış metnini döndürür: her satır bir ilçedir, ilçe adından sonra ;, mahalleler arasında |, posta kodundan önce :, birden çok posta kodu arasında , bulunur.

SEYHAN;AKKAPI MAH.:01040|ALTINŞEHİR MAH.:01170
CEYHAN;BAHÇE MAH.:01950

setLoader hook'u ve /server'ı da etkiler; hepsi aynı veri modülünü okur. Yeni bir loader daha önce okunan illeri unutturur.

Kaynak ve güncelleme

Veri, Türkiye'nin posta hizmeti PTT'den derlendi. Adlar ve posta kodları kamuya açık referans verisidir; bu paket yalnızca biçimlerini değiştirir. Teslimatın kritik olduğu işlerde PTT ile doğrulayın.

Kaynak her sokağı listeler; bu, bir adres formunun ihtiyacından çok fazladır. Derleme veriyi posta koduyla birlikte benzersiz mahallelere indirger. Her il iç içe JSON yerine tek bir kodlanmış metin olarak gelir: ağda daha küçüktür ve bir metni bölmek, nesne dizisini ayrıştırmaktan hızlıdır.

Veri her ay otomatik bir sistemle PTT'ye karşı kontrol edilir. Bir değişiklik bulunursa yeni bir patch sürümü yayınlanır; API değişmez. source.date verinin toplandığı günü verir.