Blog · Adres verisi ve rehberler
Dış Kapı Numarası Nedir? Bina Düzeyini Modellemek
Dış kapı numarası nedir, iç kapıdan farkı ne? Bina düzeyini veritabanında ve adres formunda doğru saklamak için şema, kod örnekleri ve kontrol listesi.
Adres formunda "No" alanı küçük görünür, ama veri modelinde en çok hata bu alanda çıkar. Dış kapı numarası, binanın sokağa açılan kapısına verilen numaradır ve bir adresin katalogla eşleştirilebilen son halkasıdır. Bu yazıda dış kapıyı daireden ayırmayı, numarayı bozmadan saklamayı ve seçilen kaydı kalıcı bir kimlikle tutmayı örnek kodlarla gösteriyoruz.
Dış kapı numarası ile iç kapı numarası arasındaki fark
Bir apartmanın sokaktan girilen kapısının bir numarası vardır. İçerideki her dairenin de kendi numarası vardır. İkisi farklı şeyleri tanımlar:
- Dış kapı numarası (günlük dilde bina numarası): Binayı sokak üzerinde konumlandırır. Aynı sokaktaki binaları birbirinden ayırır.
- İç kapı numarası (daire numarası): Binanın içindeki bağımsız bölümü tanımlar. Aynı binadaki daireleri birbirinden ayırır.
Örnek bir adres üzerinde gösterelim:
Caferağa Mahallesi, Moda Caddesi No: 12 B Blok Kat: 3 Daire: 7, Kadıköy/İstanbul
| Parça | Değer | Düzey |
|---|---|---|
| Mahalle | Caferağa Mahallesi | Katalog |
| Cadde/sokak | Moda Caddesi | Katalog |
| Dış kapı | 12 | Katalog (son halka) |
| Blok | B | Bina içi, serbest |
| Kat | 3 | Bina içi, serbest |
| İç kapı | 7 | Bina içi, serbest |
Formlarda sık yapılan hata, "No: 12/7" gibi tek bir alan açıp iki bilgiyi birlikte istemektir. Kullanıcı bazen "12/7", bazen "12 D:7", bazen yalnız "7" yazar. Hangi sayının bina, hangisinin daire olduğunu sonradan ayırmak çoğu zaman tahmine dönüşür.
Adres hiyerarşisinde bina düzeyinin yeri
API Türkiye kataloğundaki adres hiyerarşisi beş düzeyden oluşur ve her düzey bir öncekinin kapsamında listelenir:
- İl:
GET /v1/provinces - İlçe:
GET /v1/provinces/{code}/districts - Mahalle:
GET /v1/districts/{code}/neighborhoods - Cadde/sokak:
GET /v1/neighborhoods/{code}/streets - Dış kapı:
GET /v1/streets/{code}/buildings
Dış kapı listesi bir sokağa bağlıdır. Bu nedenle kullanıcıdan önce sokağı seçmesini, ardından o sokağın kapıları arasından seçim yapmasını istemek gerekir. Dış kapı yanıtındaki her kayıt şu alanları taşır:
{
"data": [
{ "stableId": "apt_v1_dor_...", "id": "88214", "code": "72503885", "doorNumber": "24", "label": "" }
],
"meta": { "nextCursor": null }
}
Dikkat edilecek nokta: doorNumber metin olarak döner ve aynı numara bir sokakta birden fazla kayıtla görünebilir. Bu yüzden kullanıcının seçtiği kaydı numarasıyla değil, kimliğiyle saklamak gerekir.
Hiyerarşi dış kapıda biter: daire, kat ve blok ayrı alanlarda
Katalog dış kapıda biter. Blok, kat ve daire bilgisi hiyerarşinin bir parçası değildir. Bunları formda ve veritabanında ayrı, isteğe bağlı serbest alanlar olarak ele alın:
- Blok: "B", "B Blok", "A2" gibi değerler. Her binada yoktur.
- Kat: "3", "Zemin", "Bodrum", "-1". Her zaman sayı değildir.
- Daire (iç kapı numarası): "7", "7A", "Dükkân 2". Müstakil evlerde boş kalabilir.
- Adres tarifi: "Eczanenin üstü" gibi kurye için yardımcı not.
Bu alanları zorunlu yapmayın. Müstakil bir evde daire numarası istemek, kullanıcıyı "0" ya da "-" gibi anlamsız değerler yazmaya iter. Bu değerler de sonradan veride gürültü olarak kalır.
Dış kapı numarasını sayı değil metin olarak saklayın
"12A", "5/1", "24-26" gibi numaralar sahada olağandır. Kolonu INTEGER yaparsanız bu numaraların ya kaydı reddedilir ya da harf ve kesir kısmı sessizce düşer. "12A" ile "12" aynı kayda dönüşür ve kurye yanlış binaya gider.
Kurallar basit:
- Dış kapı numarasını metin kolonda tutun. Uzunluk için doğrulama ucunun
doorNumberalanındaki 80 karakterlik üst sınır makul bir referanstır. - Numarayı
parseIntya daint()ile dönüştürmeyin; API'den geldiği gibi saklayın. - Sıralama gerekiyorsa görüntüleme katmanında "doğal sıralama" yapın; saklama biçimini sıralama için değiştirmeyin.
- Aynı kural kat ve daire alanları için de geçerlidir.
Seçilen dış kapının stableId değerini referans olarak tutun
Dış kapı kaydında üç kimlik bulunur ve hepsi aynı amaca hizmet etmez:
| Alan | Ne zaman kullanılır |
|---|---|
stableId | Kalıcı referans. Veritabanında bunu saklayın. |
code | Kaynak kodu; eşleştirme için korunabilir. |
id | Aktif katalog sürümüne ait kayıt; sürümler arasında değişebilir. |
Örnek bir tablo:
CREATE TABLE customer_address (
id BIGSERIAL PRIMARY KEY,
-- Katalog referansları (kalıcı kimlik)
province_stable_id TEXT NOT NULL,
district_stable_id TEXT NOT NULL,
neighborhood_stable_id TEXT NOT NULL,
street_stable_id TEXT NOT NULL,
door_stable_id TEXT, -- katalogdan seçilmediyse NULL
-- Seçim anındaki görünen değerler
street_name TEXT NOT NULL,
door_number VARCHAR(80) NOT NULL, -- "12", "12A", "5/1"
-- Bina içi bilgi: katalog dışı, serbest alanlar
block VARCHAR(40),
floor VARCHAR(20),
unit VARCHAR(20), -- iç kapı (daire) numarası
directions VARCHAR(300),
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
door_number kolonunu door_stable_id varken de tutmanın nedeni şudur: Siparişin verildiği andaki adresi, katalog sonradan güncellense bile aynen gösterebilirsiniz. İl, ilçe ve mahalle adları için de aynı mantıkla ad kolonları ekleyebilirsiniz. Kimlik ve metni birlikte saklama yaklaşımının ayrıntılarını adres veritabanı tasarımı yazımızda ele aldık.
Kullanıcı kapısını listede bulamazsa numarayı elle yazmasına izin verip door_stable_id alanını NULL bırakabilirsiniz. Bu kayıtları ayrıca işaretleyip gözden geçirmek, sessizce kabul etmekten daha güvenlidir.
Formda dış kapı seçimi: sunucu tarafı örnekler
API anahtarı tarayıcıya konmaz; dış kapı listesini kendi sunucunuz üzerinden çekin. Sokak içinde numara önekiyle aramak için q parametresi kullanılır:
curl "https://api.apiturkiye.com/v1/streets/173405/buildings?q=24&limit=50" \
-H "X-API-Key: apt_live_..."
Node.js tarafında formun çağıracağı bir yardımcı fonksiyon:
const BASE = "https://api.apiturkiye.com";
export async function searchDoors(streetCode, prefix, cursor) {
const url = new URL(`${BASE}/v1/streets/${encodeURIComponent(streetCode)}/buildings`);
url.searchParams.set("limit", "50");
if (prefix) url.searchParams.set("q", prefix);
if (cursor) url.searchParams.set("cursor", cursor);
const res = await fetch(url, {
headers: { "X-API-Key": process.env.APITURKIYE_KEY },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const body = await res.json();
return {
items: body.data.map((d) => ({
stableId: d.stableId,
doorNumber: d.doorNumber, // metin olarak kalır
label: d.label,
})),
nextCursor: body.meta.nextCursor,
};
}
Kullanıcı numarayı yazıp gönderdiyse ve siz eşleşen kaydı arıyorsanız, önek araması "24" için "24A" ya da "245" gibi numaraları da getirebilir. Python ile tam eşleşmeleri ayıklayıp bina içi alanları temizleyen bir örnek:
import os
import requests
BASE = "https://api.apiturkiye.com"
def find_doors(street_code, door_number):
params = {"q": door_number, "limit": 100}
matches = []
while True:
res = requests.get(
f"{BASE}/v1/streets/{street_code}/buildings",
headers={"X-API-Key": os.environ["APITURKIYE_KEY"]},
params=params,
timeout=10,
)
res.raise_for_status()
body = res.json()
matches += [d for d in body["data"] if d["doorNumber"] == door_number.strip()]
cursor = body["meta"]["nextCursor"]
if not cursor:
return matches
params["cursor"] = cursor
def clean(value, max_len):
if not value:
return None
value = " ".join(value.split())
if len(value) > max_len:
raise ValueError(f"En fazla {max_len} karakter girilebilir.")
return value or None
def build_unit_fields(form):
return {
"block": clean(form.get("block"), 40),
"floor": clean(form.get("floor"), 20),
"unit": clean(form.get("unit"), 20),
"directions": clean(form.get("directions"), 300),
}
find_doors sıfır, bir ya da birden fazla kayıt döndürebilir. Tek kayıt varsa onun stableId değerini saklayın. Birden fazla kayıt varsa kullanıcıya seçtirin; hiç kayıt yoksa elle giriş yoluna yönlendirin.
Pro ve üzeri paketlerde POST /v1/addresses/validate ucu, il'den dış kapıya kadar bileşenleri aktif katalogda kontrol eder. Bu uca gönderilen isteğe bağlı doorId, dış kapı listesindeki id değeridir; stableId değildir. id sürümler arasında değişebildiği için onu kalıcı olarak saklamak yerine, listeleme ile doğrulamanın aynı akış içinde yapıldığı durumlarda kullanın.
Kalabalık sokaklarda dış kapı listeleri
Uzun bir caddede kapı sayısı tek sayfaya sığmayabilir. Dış kapı ucu limit ve cursor ile sayfalanır; yanıttaki meta.nextCursor değeri null olana kadar devam edersiniz. Formda bütün listeyi baştan çekmek yerine kullanıcı yazdıkça q ile daraltmak hem daha hızlıdır hem de daha az istek harcar. Sayfalama döngüsünü, hata durumlarını ve "daha fazla yükle" desenini cursor sayfalama yazımızda ayrıntılı anlattık.
Kontrol listesi
- Dış kapı ile iç kapı numarası formda ayrı alanlarda.
- Blok, kat, daire ve tarif isteğe bağlı serbest alanlar; katalogla eşleştirilmeye çalışılmıyor.
- Dış kapı, kat ve daire metin kolonlarda; sayıya dönüştürme yok.
- Seçilen kapının
stableIddeğeri saklanıyor;idkalıcı referans olarak kullanılmıyor. - Seçim anındaki
doorNumbergörüntüleme için ayrıca tutuluyor. - Aynı numaralı birden fazla kayıt olasılığı arayüzde ele alınıyor.
- Listede bulunamayan kapı için elle giriş yolu var ve bu kayıtlar işaretleniyor.
- Dış kapı istekleri sunucudan yapılıyor; API anahtarı tarayıcıda değil.
Uç noktaların tam parametre ve yanıt ayrıntıları için API dokümantasyonu sayfasına bakabilirsiniz. Kendi sokak ve kapı verinizle denemek isterseniz ücretsiz kayıt olup API anahtarınızı alabilirsiniz.