yokatlas-py

YÖK Atlas tercih kılavuzu JSON API'si için modern, tip güvenli Python istemcisi.

English README · API Referansı · Migration Rehberi

⚠️ v0.6.0 büyük değişiklik içerir. YÖK Atlas Nisan 2026'da React tabanlı SPA'ya geçti ve eski HTML scraping endpoint'leri kapandı. v0.6.0, yeni JSON API'ye karşı sıfırdan yazıldı. v0.x kullanıcıları için MIGRATION.md dosyasına bakın.

Özellikler

• Tek istemci: YokAtlasClient (sync) ve AsyncYokAtlasClient (async) — aynı arayüz.
• Tek seferde 4 yıllık veri: Her program, mevcut yıl + 3 önceki yılın taban puanı, başarı sırası, kontenjan/yerleşen sayıları, akademik kadro bilgileri ile döner.
• Akıllı arama: universite="boğaziçi", program="bilgisayar", il="ankara" gibi serbest yazımlar fuzzy match ile ID'ye dönüşür (Türkçe karakter normalizasyonu dahil).
• Pydantic v2 modeller: Tam tip güvenliği, IDE auto-complete, runtime doğrulama.
• Sıfır HTML parsing: Tüm veri JSON, beautifulsoup4 bağımlılığı yok.

Kurulum

pip install yokatlas-py
# veya
uv add yokatlas-py

Python ≥3.10 gerekir.

Hızlı başlangıç

from yokatlas_py import YokAtlasClient, SearchFilters

with YokAtlasClient() as client:
    # Boğaziçi'nde sayısal tüm programlar
    page = client.search(
        SearchFilters(puan_turu="SAY", universite="boğaziçi"),
        size=20,
    )
    print(f"Toplam: {page.total_elements}")

    for prog in page.content:
        print(
            f"{prog.universite_adi} — {prog.birim_adi} | "
            f"{prog.current.min_puan} ({prog.current.basari_sirasi})"
        )

    # Tek bir program (kilavuz kodu ile)
    prog = client.get_program(102210277)
    if prog:
        for stats in prog.all_years:
            print(f"{stats.year}: {stats.min_puan} / {stats.basari_sirasi}")

Async kullanım

import asyncio
from yokatlas_py import AsyncYokAtlasClient, SearchFilters

async def main() -> None:
    async with AsyncYokAtlasClient() as client:
        page = await client.search(SearchFilters(il="ankara", program="tıp"))
        for prog in page.content:
            print(prog.universite_adi, prog.current.min_puan)

asyncio.run(main())

Modül seviyesinde kısayollar

Tek seferlik scriptler için singleton bir istemci üzerinden çalışan kısayollar:

from yokatlas_py import search_programs, get_program, list_universities

page = search_programs({"puan_turu": "EA", "universite": "boğaziçi"}, size=10)
prog = get_program(102210277)
unis = list_universities()  # 221 üniversite

Filtreler

Akıllı (string) alanlar ile ID alanları aynı anda verilemez — biri seçilir.

Yapı

Bir Program 4 yıllık veri taşır:

prog.current        # YearlyStats: en güncel yıl (2025)
prog.history        # list[YearlyStats]: 3 önceki yıl (2024, 2023, 2022)
prog.all_years      # 4 yılın tümü (yeni → eski)

YearlyStats alanları: year, kontenjan, yerlesen, kontenjan_obs, kontenjan_y34, prof, doc, dou, ogr_gor, ar_gor, kpss1, kpss2, min_puan, basari_sirasi.

Yapılandırma

YOKATLAS_* env var'ları ile veya Settings ile:

from yokatlas_py import Settings, YokAtlasClient

settings = Settings(timeout=60.0, lookup_cache_ttl=600)
client = YokAtlasClient(settings=settings)

Önemli kısıt — detaylı Atlas verileri artık yok

🛑 Detaylı atlas verileri (cinsiyet/lise alanı/yerleşen il dağılımı, tercih edilen üniversiteler/programlar, akademisyen ünvan dağılımı, yatay geçiş, mezuniyet yılı dağılımı, KPSS yıllara göre, vb. ~25 alt kategori) v0.6.0'da YOK.

Bu, kütüphanenin değil YÖK Atlas'ın kararı: Nisan 2026 SPA geçişiyle birlikte bu sayfalar siteden tamamen kaldırıldı, frontend bile artık bunları render etmiyor ve geriye parse edilebilecek bir endpoint kalmadı.

YÖK Atlas bu verileri ileride geri getirirse (yeni endpoint'ler veya genişletilmiş search response'u olarak) kütüphaneye ekleyeceğiz. Şimdilik v0.6.0 sadece resmî API'nin sunduğu kontenjan/yerleşen, akademik kadro, KPSS, taban puan, başarı sırası alanlarını (4 yıllık) döner.

Geliştirme

uv sync
uv run pytest                # tüm testler (mock)
uv run pytest -m integration # gerçek API (opt-in)
uv run mypy yokatlas_py/

Lisans

MIT