API Önbellekleme: Adres Listeleri ve Veri Sürümü
API önbellekleme ile il, ilçe ve mahalle listelerini önbelleğe alın; /v1/meta ile katalog sürümünü izleyip önbelleği doğru zamanda yenileyin.
Adres formlarında aynı listeler tekrar tekrar istenir. İl listesi her kullanıcı için aynıdır ve İstanbul'un ilçeleri gün içinde değişmez. Bu listeleri her form açılışında API'den yeniden çekmek gecikmeyi artırır ve paket kotanızı gereksiz yere tüketir. API önbellekleme bu tekrarı ortadan kaldırır. Tek zor nokta, önbelleğin ne zaman eskidiğini bilmektir. Bu yazıda hangi adres listelerinin önbelleğe uygun olduğunu, önbelleği hangi olaylarda yenilemeniz gerektiğini, katalog sürümünü /v1/meta ile nasıl izleyeceğinizi ve stableId kullanımının sürüm değişikliklerinde neden işinizi kolaylaştırdığını ele alıyoruz.
Hangi adres listeleri önbelleğe uygun?
Önbellek kararı iki soruya dayanır: Veri ne sıklıkla değişiyor ve kaç farklı anahtar oluşuyor? Adres hiyerarşisinin üst katmanları hem az değişir hem de sınırlı sayıda anahtar üretir. Alt katmanlara indikçe kayıt sayısı artar ve önbelleği isteğe bağlı doldurmak daha mantıklı hâle gelir.
| Uç | Önbellek uygunluğu | Önerilen yaklaşım |
|---|---|---|
GET /v1/provinces | Çok yüksek | Tek anahtar. Katalog sürümü değişene kadar saklayın. |
GET /v1/provinces/{code}/districts | Çok yüksek | İl başına bir anahtar. 81 il ve 973 ilçe küçük bir veri hacmidir. |
GET /v1/districts/{code}/neighborhoods | Yüksek | İlçe başına bir anahtar. Liste tek yanıtta tam gelir; tamamını saklayın. |
GET /v1/neighborhoods/{code}/streets | Orta | Mahalle ilk istendiğinde tüm sayfaları cursor ile toplayıp saklayın. |
GET /v1/streets/{code}/buildings | Düşük–orta | Yalnız istenen sokakları, daha kısa bir süreyle saklayın. |
GET /v1/autocomplete | Düşük | Sorgu çeşitliliği çok yüksektir. En fazla kısa ömürlü bir önbellek kullanın. |
POST /v1/addresses/validate | Uygun değil | Sonuç, gönderilen adrese ve aktif katalog sürümüne bağlıdır. |
İki ayrıntı sık atlanır. Mahalle listesi tek yanıtta tamamen döner. Bu listeyi önbelleğe alırken ilk 100 kayıtla sınırlamayın. Aynı mahalle adı farklı yerleşimlerde bulunabileceği için önbellekteki kayıtları ada göre tekilleştirmeyin; kimlik olarak code veya stableId kullanın.
Önbelleği ne zaman yenilemeli?
Yalnız süreye dayalı bir önbellek iki yönden hata yapar. Süre uzunsa katalog güncellendikten sonra eski veri sunarsınız. Süre kısaysa veri değişmediği hâlde gereksiz istek atarsınız. Daha sağlam bir düzen üç tetikleyiciyi birlikte kullanır:
- Katalog sürümü değişti. Asıl yenileme sinyali budur. Sürüm değiştiğinde önbellekteki tüm adres listeleri eski sayılır.
- Güvenlik süresi (TTL) doldu. Sürüm kontrolü bir sebeple aksarsa, kayıtların süresiz kalmasını bu üst sınır engeller.
- Hata durumunda bayat veriye düşme.
503 catalog_unavailableveya429yanıtı aldığınızda elinizdeki son geçerli listeyi sunmak, kullanıcıya hata göstermekten genellikle daha iyidir.
429 yanıtlarında Retry-After başlığına uyun ve isteği hemen tekrarlamayın. Bu konunun ayrıntıları 429 hatası rehberinde anlatılıyor. 401 ve 403 yanıtları bayat veriyle gizlenmemelidir. Bu durumlar anahtar, yetki veya paket sorununa işaret eder ve düzeltilmesi gerekir.
Veri sürümünü /v1/meta ile izlemek
GET /v1/meta aktif katalogun meta verisini döner. Önbelleği bu uçla ilişkilendirmenin en basit yolu, uca belirli aralıklarla istek atıp yanıtın değişip değişmediğine bakmaktır. Değişiklik varsa adres önbelleğini geçersiz sayarsınız.
curl "https://api.apiturkiye.com/v1/meta" -H "X-API-Key: apt_live_..."
Aşağıdaki Node.js örneği (Node 18 ve üzeri) /v1/meta yanıtının data alanından kısa bir parmak izi üretir. Her önbellek kaydına bu parmak izini ekler. Parmak izi değiştiğinde kayıtlar kendiliğinden geçersiz olur. Kontrol aralığı ve TTL değerleri örnek amaçlıdır; bunları kendi ihtiyacınıza göre ayarlayın.
import crypto from "node:crypto";
const BASE = "https://api.apiturkiye.com";
const API_KEY = process.env.APITURKIYE_KEY;
const TTL_MS = 24 * 60 * 60 * 1000; // güvenlik süresi
const CHECK_INTERVAL_MS = 15 * 60 * 1000; // sürüm kontrol aralığı
const cache = new Map(); // path -> { data, version, expiresAt }
let catalogVersion = null;
let lastCheck = 0;
async function apiGet(path) {
const res = await fetch(BASE + path, { headers: { "X-API-Key": API_KEY } });
if (!res.ok) {
const body = await res.json().catch(() => ({}));
const err = new Error(`HTTP ${res.status}`);
err.status = res.status;
err.code = body.error?.code;
err.retryAfter = res.headers.get("Retry-After");
throw err;
}
return res.json();
}
async function currentCatalogVersion() {
const now = Date.now();
if (catalogVersion && now - lastCheck < CHECK_INTERVAL_MS) return catalogVersion;
try {
const body = await apiGet("/v1/meta");
catalogVersion = crypto
.createHash("sha256")
.update(JSON.stringify(body.data))
.digest("hex")
.slice(0, 16);
} catch (err) {
if (!catalogVersion) throw err; // hiç sürüm bilgisi yoksa hatayı yükselt
// aksi hâlde bilinen sürümle devam et
}
lastCheck = now;
return catalogVersion;
}
export async function cachedList(path) {
const version = await currentCatalogVersion();
const entry = cache.get(path);
if (entry && entry.version === version && entry.expiresAt > Date.now()) {
return entry.data;
}
try {
const { data } = await apiGet(path);
cache.set(path, { data, version, expiresAt: Date.now() + TTL_MS });
return data;
} catch (err) {
if (entry && (err.status === 429 || err.status === 503)) return entry.data; // bayat veri
throw err;
}
}
// Kullanım
const provinces = await cachedList("/v1/provinces");
const districts = await cachedList("/v1/provinces/34/districts");
Parmak izi yaklaşımı, yanıtın alan yapısına bağımlı olmadığı için hemen çalışır. Ancak /v1/meta yanıtı her istekte değişen bir alan içeriyorsa (örneğin bir zaman damgası) bu yöntem önbelleği gereğinden sık geçersiz kılar. Bu durumda karşılaştırmayı yalnız sürümü temsil eden alanla yapın. Alan adlarını API dokümantasyonundaki /v1/meta şemasından doğrulayın.
Sürüm bilgisini başka kaynaklardan da okuyabilirsiniz
- Anahtarınızda
datasets:readyetkisi varsaGET /v1/datasets/currentyanıtındakidata.datasetVersionalanı, UUID biçiminde açık bir sürüm kimliği verir. POST /v1/addresses/validatebaşarılı yanıtındameta.datasetVersiondöner. Bu değer bilinen sürümünüzden farklıysa sürüm kontrolünü planlanan zamanı beklemeden tetikleyebilirsiniz.
Aşağıdaki Python örneği sürümü /v1/datasets/current üzerinden okur. Ayrıca cursor sayfalamalı cadde/sokak listesini mahalle bazında toplayıp önbelleğe alır.
import os
import time
import requests
BASE = "https://api.apiturkiye.com"
HEADERS = {"X-API-Key": os.environ["APITURKIYE_KEY"]}
TTL = 24 * 3600
_cache = {} # anahtar -> (sürüm, son_geçerlilik, veri)
def get_json(path, params=None):
res = requests.get(BASE + path, headers=HEADERS, params=params, timeout=10)
res.raise_for_status()
return res.json()
def dataset_version():
# datasets:read yetkisi gerektirir; her istekte değil, aralıklarla çağırın
return get_json("/v1/datasets/current")["data"]["datasetVersion"]
def all_streets(neighborhood_code):
items, cursor = [], None
while True:
params = {"limit": 100}
if cursor:
params["cursor"] = cursor
body = get_json(f"/v1/neighborhoods/{neighborhood_code}/streets", params)
items.extend(body["data"])
cursor = body["meta"]["nextCursor"]
if not cursor:
return items
def cached_streets(neighborhood_code, version):
key = f"streets:{neighborhood_code}"
hit = _cache.get(key)
if hit and hit[0] == version and hit[1] > time.time():
return hit[2]
data = all_streets(neighborhood_code)
_cache[key] = (version, time.time() + TTL, data)
return data
version = dataset_version()
streets = cached_streets("20239", version)
Örnekteki mahalle kodu yalnız gösterim amaçlıdır. Uygulamanızda mahalle listesi yanıtından aldığınız gerçek kodları kullanın.
API önbellekleme mimarisinde dikkat edilecekler
- Önbelleği sunucuda tutun. API anahtarı tarayıcıya konmaz. Ön yüz kendi sunucunuza istek atar; önbellek de bu katmanda bulunur. Birden fazla sunucu çalıştırıyorsanız bellek içi
Mapyerine paylaşılan bir önbellek deposu kullanın. Böylece sürüm değişikliği tüm örneklere aynı anda yansır. - Tarayıcı önbelleğini kendi uçlarınızla yönetin. Kendi sunucunuzun döndürdüğü il ve ilçe listelerine
Cache-Controlbaşlığı ekleyebilirsiniz. Yanıta sürüm parmak izini koyarsanız ön yüz,localStorageiçindeki eski listeyi sürüm değiştiğinde atabilir. - Eşzamanlı yenilemeyi tekilleştirin. Sürüm değiştiği anda aynı listeyi isteyen çok sayıda kullanıcı aynı API çağrısını tetikleyebilir. Devam eden isteği bir
Promiseolarak saklayıp diğer çağıranlara aynı sonucu vermek, gereksiz istekleri önler. - Doğrulama sonucunu kalıcı gerçek gibi saklamayın.
valid: trueyanıtı, o anki katalog sürümüne göre verilmiş bir sonuçtur. Siparişle birliktemeta.datasetVersiondeğerini de kaydederseniz, hangi sürüme göre doğrulandığını sonradan görebilirsiniz.
stableId ile sürüm değişikliklerine dayanıklılık
Önbelleği yenilemek listeleri günceller. Peki daha önce veritabanınıza kaydettiğiniz adreslere ne olur? Burada belirleyici olan, referans olarak hangi alanı sakladığınızdır.
Her kayıt, sürümden bağımsız bir stableId taşır. Kullanıcının seçtiği il, ilçe, mahalle, sokak ve kapıyı stableId ile saklarsanız katalog sürümü değiştiğinde kayıtlarınız boşa düşmez. Yeni önbellekteki listelerde aynı stableId değerini bulup güncel adı gösterebilirsiniz. Yeni listede bulunamayan bir stableId, ilgili adresin gözden geçirilmesi gerektiğini gösteren somut bir sinyaldir.
Dış kapılardaki id alanının durumu farklıdır. Bu alan aktif katalog sürümüne aittir ve sürümler arasında değişebilir. Bu yüzden id değerini kalıcı referans olarak saklamayın ve önbellekteki kapı listelerini sürüm değiştikten sonra kullanmayın. Doğrulama isteğinde doorId göndermeniz gerekiyorsa değeri güncel sürümün /v1/streets/{code}/buildings yanıtından alın. code alanını kaynakla eşleştirme için yanında tutabilirsiniz.
Bu ayrımı veritabanı şemasına nasıl yansıtacağınızı Adres Veritabanı Tasarımı: Metin Değil, Kalıcı Kimlik yazısında ayrıntılı olarak bulabilirsiniz.
Kısa kontrol listesi
- İl, ilçe ve mahalle listelerini katalog sürümüne bağlı olarak önbelleğe alın.
- Cadde/sokak ve dış kapı listelerini isteğe bağlı doldurun; dış kapılar için daha kısa bir süre kullanın.
- Sürümü
/v1/metaile düzenli aralıklarla kontrol edin. UygunsadatasetVersionalanından da yararlanın. - TTL'yi bir güvenlik ağı olarak kullanın. Asıl yenileme sinyali sürüm değişikliği olsun.
429ve503yanıtlarında son geçerli veriyi sunun.401ve403yanıtlarını gizlemeyin.- Kalıcı referans olarak
stableIdsaklayın. Dış kapıiddeğerini kalıcı referans olarak saklamayın.
Sonraki adım
Uçların ve yanıt alanlarının tam listesi API dokümantasyonunda yer alıyor. Kendi önbellek katmanınızı denemek için ücretsiz kayıt olup API anahtarınızı alabilir, paketlerin kapsamını da paket karşılaştırması bölümünde inceleyebilirsiniz.