Blog · Entegrasyon ve mimari

Cursor Sayfalama: Büyük Sokak ve Kapı Listeleri

Cursor sayfalama ile sokak ve dış kapı listelerini nextCursor üzerinden verimli çekin: son sayfa, filtre değişimi ve ihtiyaç kadar veri istemek.

5 dk okuma

Bir mahallenin sokak listesi ya da uzun bir caddenin dış kapıları tek bir yanıta sığmayacak kadar uzun olabilir. API Türkiye bu listeleri cursor sayfalama ile sunar. Her yanıt, bir sonraki sayfanın nereden başlayacağını meta.nextCursor alanında bildirir. Bu yazıda cursor yaklaşımının OFFSET'ten neden daha uygun olduğu ele alınıyor. Ardından son sayfayı nasıl anlayacağınız, filtre değiştiğinde neden baştan başlamanız gerektiği ve listenin tamamı yerine ihtiyacınız kadarını nasıl isteyeceğiniz çalışan örneklerle gösteriliyor.

OFFSET yerine neden cursor sayfalama?

Klasik pagination yaklaşımında istemci "ilk 1000 kaydı atla, sonraki 50'yi ver" der. SQL'deki karşılığı OFFSET 1000 LIMIT 50 ifadesidir. Kısa listelerde bu yöntem sorun çıkarmaz, ancak iki zayıf noktası vardır:

  • Derinleştikçe pahalılaşır. Atlanan satırların yine de taranması gerekir. Sayfa numarası büyüdükçe her istek, sunucu için daha fazla iş demektir.
  • Kayan pencere sorunu doğurur. İki istek arasında listeye kayıt eklenir ya da listeden kayıt silinirse satırlar kayar. Sonuçta aynı kaydı iki kez görebilir veya bir kaydı hiç göremeyebilirsiniz.

Cursor ise "kaldığın yerden devam et" anlamına gelir. Sunucu, son döndürdüğü konumu bir işaretçiye dönüştürür. Siz bu işaretçiyi bir sonraki istekte geri gönderirsiniz. Böylece her sayfa, listenin başından sayılarak değil, bir önceki sayfanın bittiği yerden üretilir.

API Türkiye'de yüksek OFFSET desteklenmez. Sayfalı uçlarda ilerlemenin tek yolu cursor parametresidir.

Cursor değerini opak bir dize olarak görün. İçeriğini çözümlemeye, değiştirmeye veya kendiniz üretmeye çalışmayın. API'nin verdiği değeri olduğu gibi geri gönderin. Kayıtlara kalıcı referans gerekiyorsa cursor'ı değil, kaydın stableId alanını saklayın.

Hangi uçlar sayfalı?

Her liste ucu sayfalı değildir. Hiyerarşinin üst katmanları tek yanıtta gelir. Cadde/sokak ve dış kapı katmanları ise cursor ile sayfalanır.

UçSayfalamaNot
GET /v1/provincesYokTüm iller tek yanıtta gelir.
GET /v1/provinces/{code}/districtsYokİlin tüm ilçeleri tek yanıtta gelir.
GET /v1/districts/{code}/neighborhoodsYokTek yanıtta gelir; istemcide ilk 100 kayıtla sınırlamayın.
GET /v1/neighborhoods/{code}/streetsCursorlimit 1–100, varsayılan 50.
GET /v1/streets/{code}/buildingsCursorlimit 1–100, varsayılan 50; ek olarak q ile kapı numarası öneki araması yapılabilir.
GET /v1/autocompleteYokEn fazla 20 öneri döner.
Veri seti geçmişi ve snapshot listeleriCursorlimit 1–100, varsayılan 20.

Sayfalı olmayan uçlara limit veya cursor göndermeyin. Bu uçların yanıtında meta.nextCursor da bulunmaz. Ortak bir yardımcı fonksiyon yazıyorsanız bu ayrımı açıkça kodlayın.

nextCursor ile sonraki sayfayı istemek

Akış üç adımdan oluşur:

  1. İlk isteği cursor olmadan gönderin.
  2. Yanıttaki meta.nextCursor değerini okuyun.
  3. Bu değeri bir sonraki istekte cursor parametresi olarak gönderin.

İlk sayfa şöyle istenir:

curl "https://api.apiturkiye.com/v1/neighborhoods/20239/streets?limit=50" \
  -H "X-API-Key: apt_live_..."
{
  "data": [ { "stableId": "apt_v1_str_...", "code": "173405", "name": "Moda Caddesi" } ],
  "meta": { "nextCursor": "eyJuYW1lLi4u" }
}

İkinci sayfa için cursor değerini URL kodlamasıyla ekleyin. Cursor, URL'de özel anlam taşıyan karakterler içerebilir:

curl --get "https://api.apiturkiye.com/v1/neighborhoods/20239/streets" \
  --data-urlencode "limit=50" \
  --data-urlencode "cursor=eyJuYW1lLi4u" \
  -H "X-API-Key: apt_live_..."

Buradaki kodlar ve cursor değeri sözleşmeyi göstermek içindir. Uygulamanızda liste yanıtlarından aldığınız gerçek kodları kullanın.

Sunucu tarafında tek sayfayı getiren küçük bir fonksiyon, hem arayüz hem toplu işler için iyi bir yapı taşıdır. API anahtarı tarayıcıya konmamalıdır. Bu yüzden bu fonksiyon sizin sunucunuzda çalışmalıdır:

// Sunucu tarafı (Node.js 18+): tek sayfa dış kapı getirir
export async function fetchDoorsPage({ streetCode, q, cursor, limit = 50 }) {
  const url = new URL(
    `https://api.apiturkiye.com/v1/streets/${encodeURIComponent(streetCode)}/buildings`
  );
  url.searchParams.set("limit", String(limit));
  if (q) url.searchParams.set("q", q);
  if (cursor) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, {
    headers: { "X-API-Key": process.env.APITURKIYE_KEY },
  });
  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(`${res.status} ${body.error?.code ?? "unknown_error"}`);
  }
  const body = await res.json();
  return { items: body.data, nextCursor: body.meta?.nextCursor ?? null };
}

URLSearchParams kodlamayı sizin yerinize yapar. Cursor'ı elle URL'ye eklemeyin.

Son sayfayı anlamak

Kural basittir: meta.nextCursor değeri null ise son sayfadasınız.

{
  "data": [ { "stableId": "apt_v1_dor_...", "id": "88214", "code": "72503885", "doorNumber": "24", "label": "" } ],
  "meta": { "nextCursor": null }
}

Bu sinyalin yerine başka tahminler kullanmayın:

  • "Gelen kayıt sayısı limit değerinden azsa son sayfadır" varsayımına güvenmeyin. Son sayfa kararını yalnız nextCursor belirler.
  • Boş data dizisini hata olarak yorumlamayın. İlk istekte boş dizi gelmesi, o kapsamda kayıt olmadığı anlamına gelir. Örneğin q önekiyle eşleşen kapı yoktur. Arayüzde bunu "sonuç bulunamadı" olarak gösterin.
  • Döngü koşulunu nextCursor üzerine kurun. Bu sayede sonsuz döngü ya da eksik sayfa riski ortadan kalkar.

Filtre değişince baştan başlamak

Bir cursor, onu üreten sorguya aittir. Sorgunun herhangi bir parçası değişirse eldeki cursor artık geçerli bir konum göstermez. Bu parçalar şunlardır:

  • Yoldaki mahalle veya sokak kodu
  • q arama değeri
  • limit

Böyle bir değişiklikte cursor'ı ve biriken listeyi sıfırlayıp ilk sayfadan başlayın. API'nin geçersiz bulduğu cursor için 400 invalid_cursor döndüğünü de unutmayın. Bu hatayı alırsanız aynı cursor'ı tekrar göndermek yerine listeyi baştan yükleyin. Sayfalar boyunca limit değerini sabit tutmak da iyi bir alışkanlıktır.

Arayüz tarafında kullanıcı hızlı yazarken eski bir isteğin yanıtı yenisinden sonra gelebilir. Aşağıdaki örnek, sıfırlama mantığıyla birlikte bu yarış durumunu da ele alır. İstekler, yukarıdaki fonksiyonu kullanan kendi sunucunuzdaki /api/doors ucuna gider:

// Tarayıcı tarafı: kendi sunucunuzdaki /api/doors ucunu çağırır
let state = { streetCode: null, q: "", cursor: null, items: [], done: false };
let requestSeq = 0;

async function loadPage({ reset = false } = {}) {
  if (reset) state = { ...state, cursor: null, items: [], done: false };
  if (state.done || !state.streetCode) return;

  const seq = ++requestSeq;
  const params = new URLSearchParams({ street: state.streetCode, limit: "50" });
  if (state.q) params.set("q", state.q);
  if (state.cursor) params.set("cursor", state.cursor);

  const res = await fetch(`/api/doors?${params}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const { items, nextCursor } = await res.json();

  if (seq !== requestSeq) return; // Daha yeni bir istek başladı; bu yanıtı yok say
  state.items = [...state.items, ...items];
  state.cursor = nextCursor;
  state.done = nextCursor === null;
}

function onStreetChange(code) { state.streetCode = code; loadPage({ reset: true }); }
function onSearchChange(q) { state.q = q.trim(); loadPage({ reset: true }); }
function onLoadMore() { loadPage(); }

Tüm listeyi değil, ihtiyaç kadarını isteyin

Cursor sayfalama, listenin tamamını indirmeniz gerektiği anlamına gelmez. Çoğu senaryoda kullanıcının aradığı tek bir kayıttır.

  • Kapı numarası biliniyorsa q kullanın. GET /v1/streets/{code}/buildings?q=24 yalnız o sokakta "24" ile başlayan kapı numaralarını döner ve cursor ile birlikte çalışır. Sokağın tüm kapılarını çekip istemcide filtrelemekten çok daha az istek gerektirir.
  • Sokak adı aranıyorsa autocomplete kullanın. Bir mahallenin sokak listesinin tamamını indirmek yerine aramayı mahalleyle sınırlayın:
curl --get "https://api.apiturkiye.com/v1/autocomplete" \
  --data-urlencode "q=moda cad" \
  --data-urlencode "neighborhoodCode=20239" \
  --data-urlencode "types=street" \
  --data-urlencode "limit=10" \
  -H "X-API-Key: apt_live_..."
  • Arayüzde ilk sayfayla başlayın. Sonraki sayfaları "Daha fazla göster" düğmesi veya sonsuz kaydırma ile, yalnız kullanıcı talep ettiğinde isteyin.
  • Aradığınızı bulunca durun. Async generator kullanıyorsanız break, kalan sayfaların istenmesini de engeller:
// Rehberdeki allStreets(neighborhoodCode, apiKey) generator'ı ile
const firstHundred = [];
for await (const street of allStreets("20239", process.env.APITURKIYE_KEY)) {
  firstHundred.push(street);
  if (firstHundred.length === 100) break; // Sonraki sayfalar hiç istenmez
}
  • Sık kullanılan listeleri önbelleğe alın. Aynı mahallenin sokak listesini her kullanıcı için yeniden istemeniz gerekmez. Ayrıntılar için adres listelerini önbelleğe alma yazısına bakabilirsiniz.
  • Kataloğun tamamı gerekiyorsa toplu dosyaları değerlendirin. Tüm ülkenin kapı verisini sayfa sayfa dolaşmak yerine snapshot dosyaları Ultra paketinde sunulur. Paket farklarını paket karşılaştırması bölümünde görebilirsiniz.

Tüm sayfaları dolaşmanız gerektiğinde

Bir sokağın bütün kapılarını kendi veritabanınıza aktarmak gibi durumlarda döngüyü sunucuda, hız sınırına saygılı biçimde kurun. Aşağıdaki Python örneği iki tür 429 yanıtını birbirinden ayırır. rate_limit_exceeded için Retry-After süresi kadar bekleyip aynı cursor ile tekrar dener. quota_exceeded gibi diğer hatalarda ise durur:

import os
import time
import requests

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


def iter_buildings(street_code, q=None, limit=100, max_retries=3):
    cursor = None
    retries = 0
    while True:
        params = {"limit": limit}
        if q:
            params["q"] = q
        if cursor:
            params["cursor"] = cursor

        res = requests.get(
            f"{BASE}/v1/streets/{street_code}/buildings",
            headers=HEADERS, params=params, timeout=10,
        )

        if res.status_code == 429:
            code = res.json().get("error", {}).get("code")
            if code == "rate_limit_exceeded" and retries < max_retries:
                retries += 1
                time.sleep(int(res.headers.get("Retry-After", "1")))
                continue  # Aynı cursor ile tekrar dene
        res.raise_for_status()
        retries = 0

        body = res.json()
        yield from body["data"]
        cursor = body["meta"]["nextCursor"]
        if cursor is None:
            break


for door in iter_buildings("173405"):
    print(door["stableId"], door["doorNumber"])

Bekleme ve yeniden deneme stratejisinin ayrıntılarını 429 hatasının nasıl ele alınacağını anlatan yazıda bulabilirsiniz. 401 ve 403 yanıtlarında ise anahtar, paket veya yetki sorunu düzeltilmeden otomatik tekrar yapmayın.

Kontrol listesi

  1. Sayfalı uçları (sokak, dış kapı, veri seti geçmişi, snapshot) sayfasız uçlardan (il, ilçe, mahalle, autocomplete) ayırın.
  2. İlk isteği cursor olmadan gönderin, sonrakilerde meta.nextCursor değerini aynen iletin.
  3. Son sayfa kararını yalnız nextCursor === null ile verin.
  4. Mahalle, sokak, q veya limit değiştiğinde cursor'ı ve listeyi sıfırlayın.
  5. 400 invalid_cursor aldığınızda listeyi baştan yükleyin.
  6. Kapı numarası için q, sokak adı için autocomplete kullanın; gereksiz sayfaları istemeyin.
  7. Kalıcı referans olarak cursor'ı değil stableId değerini saklayın.
  8. API anahtarını sunucuda tutun; tarayıcı yalnız kendi sunucunuzla konuşsun.

Sonraki adım

Sayfalı uçların parametrelerini ve hata kodlarını API dokümantasyonu sayfasında ayrıntılı olarak bulabilirsiniz. Örnekleri kendi verinizle denemek için ücretsiz kayıt olup API anahtarınızı alabilir, ilk sokak listenizi birkaç satır kodla çekebilirsiniz.