Overview

yokatlas-py is a modern, type-safe Python wrapper for the YÖKATLAS API with pydantic validation. It provides programmatic access to Turkish university and program data.

YÖKATLAS (Higher Education Program Atlas) is Turkey's official university admission information system managed by YÖK (Council of Higher Education - Turkey's central higher education authority).

Features

Type Safety: Full type hints with pydantic validation
Modern Python: Up-to-date syntax requiring Python 3.9+
Fast HTTP: httpx for sync and async operations
Smart Search: Fuzzy matching for universities and programs
Comprehensive Data: 235 undergraduate and 176 associate degree institutions
IDE Support: Advanced autocomplete and error detection

Installation

# with pip
pip install yokatlas-py

# with uv (recommended)
uv add yokatlas-py

Usage Examples

Smart Undergraduate Program Search

from yokatlas_py import search_lisans_programs

results = search_lisans_programs({
    "uni_adi": "boğaziçi",      # University name
    "program_adi": "bilgisayar", # Program name (computer)
    "sehir": "istanbul"          # City
})

Type-Safe Search

from yokatlas_py.models import SearchParams

params = SearchParams(
    puan_turu="say",    # Score type: say=science, söz=social, ea=equal weight, dil=language
    length=10,
    sehir="İstanbul"
)

Traditional API Usage

from yokatlas_py import YOKATLASLisansTercihSihirbazi

search = YOKATLASLisansTercihSihirbazi({
    'puan_turu': 'say',
    'sehir': 'ANKARA',
    'length': 5
})
results = search.search()

Search Parameters

uni_adi: University name (fuzzy matching supported)
program_adi: Program name
sehir: City
puan_turu: Score type
- say = Science (Math-heavy programs like Engineering, Medicine)
- söz = Social Sciences (Law, Literature)
- ea = Equal Weight (Business, Economics)
- dil = Language (Translation, Language studies)
uni_turu: Institution type (State / Foundation/Private)
ucretli: Paid / Free programs
burslu: Scholarship programs
ogretim_turu: Education type (Day / Evening programs)

Data Content

Minimum and maximum admission scores
Quota information
Enrolled student profile statistics
Preference ranking (which choice number students get placed with)
Success ranking changes over years

License

MIT License

yokatlas-py