yokatlas-py

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