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.

4 dk okuma

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çaDeğerDüzey
MahalleCaferağa MahallesiKatalog
Cadde/sokakModa CaddesiKatalog
Dış kapı12Katalog (son halka)
BlokBBina içi, serbest
Kat3Bina içi, serbest
İç kapı7Bina 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:

  1. İl: GET /v1/provinces
  2. İlçe: GET /v1/provinces/{code}/districts
  3. Mahalle: GET /v1/districts/{code}/neighborhoods
  4. Cadde/sokak: GET /v1/neighborhoods/{code}/streets
  5. 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 doorNumber alanındaki 80 karakterlik üst sınır makul bir referanstır.
  • Numarayı parseInt ya da int() 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:

AlanNe zaman kullanılır
stableIdKalıcı referans. Veritabanında bunu saklayın.
codeKaynak kodu; eşleştirme için korunabilir.
idAktif 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 stableId değeri saklanıyor; id kalıcı referans olarak kullanılmıyor.
  • Seçim anındaki doorNumber gö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.