Blog · Entegrasyon ve mimari

Adres Veritabanı Tasarımı: Metin Değil, Kalıcı Kimlik

Adres veritabanı tasarımında metin yerine stableId saklamanın nedenleri: code ile farkı, şema önerisi ve isimleri görüntüleme için ayrı tutmak.

5 dk okuma

Bir sipariş tablosunda city = 'İstanbul' yazan bir sütun ilk bakışta yeterli görünür. Sorunlar daha sonra çıkar: raporda aynı mahalle iki ayrı satırda görünür, bir sorgu büyük harfle kaydedilmiş adresleri kaçırır, adı güncellenen bir sokak eski kayıtlarla eşleşmez. Adres veritabanı tasarımında asıl soru, kaydın neyi gösterdiği değil, neye işaret ettiğidir. Bu yazıda adres kayıtlarını stableId ile nasıl modelleyeceğinizi, code alanının bu modeldeki yerini ve görüntüleme için isimleri neden ayrıca saklamanız gerektiğini örneklerle ele alıyoruz.

Metin karşılaştırmasının tuzakları

Adresi metin olarak saklayıp metinle eşleştirmek, her karşılaştırmayı küçük bir tahmine dönüştürür. Karşılaşacağınız başlıca sorunlar şunlardır:

  • Büyük/küçük harf ve Türkçe karakterler. Varsayılan dönüşümler Türkçe İ ve I harflerini doğru işlemez.
  • Ekler ve kısaltmalar. Caferağa, Caferağa Mah. ve CAFERAĞA MAHALLESİ aynı yeri anlatır ama üç farklı metindir. Moda Cad. ile Moda Caddesi için de durum aynıdır.
  • Aynı ad, farklı yer. Aynı mahalle adı farklı yerleşimlerde bulunabilir. Yalnız ada bakarak birleştirme yaparsanız iki ayrı yeri tek kayıt sanırsınız.
  • Kaynağın kendi biçimi. Aynı API'nin farklı uçları farklı yazım döndürebilir. Örneğin il listesi örneğinde ad İstanbul, doğrulama yanıtı örneğinde ise İSTANBUL biçimindedir.
  • Ad değişiklikleri. Yeni bir veri sürümünde bir adın yazımı değiştiğinde, metne dayalı birleştirmeler sessizce kırılır ve raporlar ikiye bölünür.

İlk madde için kısa bir JavaScript örneği:

"İSTANBUL".toLowerCase() === "istanbul";           // false: sonuç "i" + U+0307 birleşik nokta içerir
"İSTANBUL".toLocaleLowerCase("tr") === "istanbul"; // true
"ISPARTA".toLowerCase();                           // "isparta"
"ISPARTA".toLocaleLowerCase("tr");                 // "ısparta"

Normalleştirme kurallarınızı ne kadar genişletirseniz genişletin, her yeni istisna için bir kural daha yazmanız gerekir. Kimlik ile eşleştirme bu sorunların hiçbirine bağlı değildir: iki kayıt aynı kimliği taşıyorsa aynı yerdir.

stableId, code ve id: hangisi ne için?

API Türkiye yanıtlarında üç kimlik alanı bulunur. Her birinin veri modelinizdeki rolü farklıdır:

AlanNedir?Sizdeki rolü
stableIdKalıcı, sürümden bağımsız kimlikBirincil referans; ilişki ve raporlamada bunu kullanın
codeKaynak kodu; il için sayısal, diğer düzeylerde metinSonraki API çağrıları ve eşleştirme için yardımcı alan
idYalnız dış kapılarda; aktif katalog sürümüne ait kayıtKalıcı referans olarak saklamayın; sürümler arasında değişebilir

stableId kaydın kalıcı kimliğidir. Entegrasyonların referans olarak saklaması gereken alan budur; adın yazımından ve katalog sürümünden bağımsızdır.

code ise API ile konuşmak için gereklidir. Uç yolları kodla çalışır (/v1/provinces/{code}/districts, /v1/districts/{code}/neighborhoods), autocomplete aramasını daraltan provinceCode, districtCode ve neighborhoodCode parametreleri de kod bekler. Bu yüzden iki alanı birlikte saklamak mantıklıdır: stableId referans için, code sonraki çağrılar için.

Tür konusunda dikkat edilecek bir nokta var: il kodu il listesinde sayı olarak (34), doğrulama ve autocomplete yanıtlarında ise metin olarak ("34") gelir. İl kodu resmî plaka koduyla aynıdır. Bu nedenle il kodunu tamsayı sütununda tutmak "01" ile 1 arasındaki biçim farkını ortadan kaldırır. Diğer düzeylerin kodlarını ise metin olarak saklamak dönüşüm hatalarını önler.

Dış kapılardaki id alanı, doğrulama isteğindeki isteğe bağlı doorId parametresi için kullanılır ve aynı kapı numarasındaki farklı kayıtları ayırmaya yarar. Ancak sürümler arasında değişebileceği için kalıcı referans olarak uygun değildir; dış kapıyı da stableId ile saklayın.

Adres veritabanı tasarımı için şema önerisi

Aşağıdaki PostgreSQL şeması, bir müşteri adres defteri için dört sütun grubu kullanır: referans, eşleştirme, görüntüleme ve kullanıcı girdisi.

CREATE TABLE customer_addresses (
  id                      bigserial PRIMARY KEY,
  customer_id             bigint NOT NULL,

  -- 1) Referans: kalıcı kimlikler
  province_stable_id      text NOT NULL,
  district_stable_id      text NOT NULL,
  neighborhood_stable_id  text NOT NULL,
  street_stable_id        text,
  door_stable_id          text,

  -- 2) Eşleştirme ve sonraki API çağrıları için kaynak kodları
  province_code           smallint NOT NULL,
  district_code           text NOT NULL,
  neighborhood_code       text NOT NULL,
  street_code             text,
  door_code               text,

  -- 3) Görüntüleme: kayıt anındaki adların kopyası
  province_name           text NOT NULL,
  district_name           text NOT NULL,
  neighborhood_name       text NOT NULL,
  neighborhood_label      text,
  street_name             text,
  door_number             text,
  normalized_address      text,

  -- 4) Katalogda olmayan, kullanıcının girdiği ayrıntılar
  address_detail          text,          -- kat, daire, tarif

  dataset_version         uuid,          -- doğrulamanın yapıldığı sürüm
  verified_at             timestamptz,
  created_at              timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX idx_addr_neighborhood ON customer_addresses (neighborhood_stable_id);
CREATE INDEX idx_addr_street       ON customer_addresses (street_stable_id);

Bu şemada birkaç tasarım kararı öne çıkıyor:

  1. Sorgular ve raporlar kimlikle çalışır. "Bu mahalleye kaç teslimat yaptık?" sorusu neighborhood_stable_id üzerinden yanıtlanır; adın nasıl yazıldığı sonucu etkilemez.
  2. Katalog dış kapıda biter. Kat, daire ve adres tarifi kullanıcıdan gelir; bunları katalog alanlarıyla karıştırmadan ayrı bir sütunda tutun.
  3. Sürüm bilgisi kayda eşlik eder. dataset_version, adresin hangi katalog sürümünde doğrulandığını gösterir ve ileride yenileme kararlarında işinize yarar.
  4. Yabancı anahtar yalnız gerçek bir tabloya. Kataloğu kendi veritabanınıza yansıtıyorsanız stableId sütunlarını yerel tablolara yabancı anahtar olarak bağlayabilirsiniz. Yansıtmıyorsanız var olmayan bir tabloya kısıt eklemeye çalışmayın; kimlikler yine de tutarlı bir referans işlevi görür.

Kimlikleri doğrulama yanıtından alın

Pro ve üzeri paketlerdeki adres doğrulama ucu, eşleşen her bileşen için stableId, code ve name döndürür. Bu yanıt, yukarıdaki şemayı doldurmak için doğrudan kullanılabilir:

curl "https://api.apiturkiye.com/v1/addresses/validate" \
  -H "X-API-Key: apt_live_..." \
  -H "Content-Type: application/json" \
  --data '{"province":"İstanbul","district":"Kadıköy","neighborhood":"Caferağa Mahallesi","street":"Moda Caddesi","doorNumber":"12"}'

Sunucu tarafında yanıtı bir veritabanı satırına dönüştüren Node.js fonksiyonu:

async function validateAndBuildRow(input, addressDetail) {
  const res = await fetch("https://api.apiturkiye.com/v1/addresses/validate", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.APITURKIYE_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(input), // { province, district, neighborhood, street, doorNumber }
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);

  const { data, meta } = await res.json();
  if (!data.valid) {
    return { valid: false, failedAt: data.failedAt, suggestions: data.suggestions };
  }

  const c = data.components;
  return {
    valid: true,
    row: {
      province_stable_id: c.province.stableId,
      district_stable_id: c.district.stableId,
      neighborhood_stable_id: c.neighborhood.stableId,
      street_stable_id: c.street.stableId,
      door_stable_id: c.door.stableId,

      province_code: Number(c.province.code),
      district_code: c.district.code,
      neighborhood_code: c.neighborhood.code,
      street_code: c.street.code,
      door_code: c.door.code,

      province_name: c.province.name,
      district_name: c.district.name,
      neighborhood_name: c.neighborhood.name,
      street_name: c.street.name,
      door_number: c.door.doorNumber,
      normalized_address: data.normalizedAddress,

      address_detail: addressDetail,
      dataset_version: meta.datasetVersion,
      verified_at: new Date().toISOString(),
    },
  };
}

Eşleşmeyen adres de HTTP 200 döner; kararınızı data.valid ve data.failedAt alanlarına göre verin. Doğrulama akışının ayrıntılarını adres doğrulama entegrasyonu yazısında bulabilirsiniz.

Core paketinde ise kimlikleri kullanıcının seçim yaptığı listelerden alırsınız: il, ilçe, mahalle ve sokak listelerindeki her kayıt stableId ve code taşır. Kullanıcının seçtiği kaydın bu alanlarını forma gizli değer olarak bağlamanız yeterlidir. Kademeli form kurulumu için il, ilçe ve mahalle seçimli adres formu yazısına göz atabilirsiniz.

Görüntüleme için isimleri ayrıca saklamak

Kimlik referansı tek başına ekranda bir şey ifade etmez. Adları kayıtla birlikte saklamanın birkaç pratik gerekçesi vardır:

  • Hız ve maliyet. Her adres gösteriminde API'ye gitmek gereksiz istek ve gecikme demektir.
  • Tarihsel doğruluk. Bir siparişin kargo etiketinde veya faturasında, sipariş anındaki adres görünmelidir.
  • Bağımsızlık. API'ye geçici olarak erişilemediğinde adres defteriniz çalışmaya devam eder.

Burada kritik ilke şudur: adlar bir kopyadır, doğruluk kaynağı kimliktir. Eşleştirme, gruplama ve birleştirme işlemlerini hiçbir zaman ad sütunlarıyla yapmayın.

Mahalle seçiminde aynı adın farklı yerleşimlerde bulunabileceğini hatırlayın. Mahalle liste yanıtı locality alanını içerdiği için DEMİROLUK (ÇAVUŞOĞLU) gibi ayırt edici bir etiket üretip neighborhood_label sütununa yazabilirsiniz.

Ne zaman yenilemeli? İki tür kaydı ayırın: siparişe bağlı adres o anın fotoğrafıdır ve değiştirilmemelidir; müşterinin adres defteri ise güncel adlarla gösterilebilir. Adres defterini yenilemek için ilçe koduyla mahalle listesini alıp kayıtları stableId ile eşleştirebilirsiniz:

import os, requests

API = "https://api.apiturkiye.com"
HEADERS = {"X-API-Key": os.environ["APITURKIYE_KEY"]}

def neighborhoods_by_stable_id(district_code):
    res = requests.get(
        f"{API}/v1/districts/{district_code}/neighborhoods",
        headers=HEADERS,
        timeout=10,
    )
    res.raise_for_status()
    return {n["stableId"]: n for n in res.json()["data"]}

def build_name_updates(rows):
    """rows: adres defteri kayıtları (dict). İlçe başına tek istek atılır."""
    cache, updates, review = {}, [], []
    for row in rows:
        code = row["district_code"]
        if code not in cache:
            cache[code] = neighborhoods_by_stable_id(code)
        current = cache[code].get(row["neighborhood_stable_id"])
        if current is None:
            review.append(row["id"])  # silmeyin; incelemeye alın
            continue
        label = f'{current["name"]} ({current["locality"]["village"]["name"]})'
        updates.append((row["id"], current["name"], label))
    return updates, review

Bu örnekte eski ad ile yeni ad karşılaştırılmıyor; eşleşme kimlikle yapılıyor ve güncel ad doğrudan yazılıyor. Bunun nedeni, farklı uçların aynı yeri farklı biçimde yazabilmesidir: doğrulama yanıtından gelen bir adı liste ucundan gelen adla karşılaştırırsanız, gerçekte değişmemiş kayıtları değişmiş sanabilirsiniz. İlçe listesi tek yanıtta tamamını döndürdüğü için ilçe başına tek istek yeterlidir.

Yenileme işini rastgele aralıklarla çalıştırmak yerine katalog sürümüne bağlayabilirsiniz. Anahtarınızda datasets:read yetkisi varsa GET /v1/datasets/current yanıtındaki datasetVersion değerini kayıtlarınızdaki dataset_version ile karşılaştırın; yalnız sürüm değiştiğinde yenileme yapın.

Kısa kontrol listesi

  • Her adres düzeyi için stableId saklıyor musunuz?
  • Sonraki API çağrıları için code alanları da kayıtlı mı; il kodu tamsayı, diğerleri metin mi?
  • Dış kapının sürüme bağlı id değerini kalıcı referans olarak kullanmaktan kaçındınız mı?
  • Raporlar ve birleştirmeler yalnız kimlik sütunlarıyla mı çalışıyor?
  • Adlar görüntüleme kopyası olarak ayrı sütunlarda mı; sipariş adresi ile adres defteri ayrı ele alınıyor mu?
  • Kat, daire ve tarif gibi kullanıcı girdileri katalog alanlarından ayrı mı?
  • Doğrulama yapılan katalog sürümü kayda yazılıyor mu?

Sonraki adım

Kalıcı kimlik üzerine kurulu bir veri modeli, adres verisindeki yazım farklarını ve sürüm değişikliklerini uygulamanızın geri kalanından yalıtır. Uçların tüm alanlarını ve yetki gereksinimlerini API dokümantasyonunda inceleyebilir, Core paketiyle ücretsiz kayıt olarak API anahtarınızı alabilir ve doğrulama özelliklerini içeren paketleri paket karşılaştırmasında görebilirsiniz.