YÖK Atlas — Türkiye University Program & Admission Statistics

Retrieves official program-level statistics from YÖK Atlas (Yükseköğretim Kurulu Atlası — the Council of Higher Education's program atlas) for any undergraduate (lisans) or associate (önlisans) program in Türkiye: quotas, placements, minimum admission scores, success ranks, and academic-staff head counts by title. It wraps the keyless YÖK Atlas JSON API through the maintained yokatlas-py package, so the same query yields the same structured records — no HTML scraping, no API key.

This is the statistics skill. It does not look up an individual academic's CV, publications, or affiliation — that is alterlab-yok-akademik, a separately architected YÖK system (see the routing table below).

When to Use This Skill

Use it when the user wants program- or university-level numbers from YÖK Atlas:

YÖK Atlas'tan Boğaziçi Bilgisayar Mühendisliği taban puanını ve başarı sırasını çıkar
Compare the kontenjan and yerleşen counts for all Tıp programs at state universities
What was the minimum SAY score for Hacettepe Elektrik-Elektronik Mühendisliği last year?
List every university in YÖK Atlas and the academic-staff counts for a given program
How many professors vs. araştırma görevlisi does this department have?

→ Run scripts/yokatlas_lookup.py (a thin yokatlas-py wrapper), read the JSON, then present the requested statistics as a table. Always state the data year and that figures come from YÖK Atlas.

Canonical Turkish terms (English gloss on first use)

Academic-staff title counts are returned as prof (profesör), doc (doçent), dou (doktor öğretim üyesi), ogr_gor (öğretim görevlisi), and ar_gor (araştırma görevlisi — research assistant).

⚠️ Endpoint caveat (read before scraping anything)

As of April 2026 YÖK Atlas migrated from server-rendered PHP to a React SPA backed by a JSON API. The legacy PHP endpoints are dead — lisans.php?y=…, lisans-panel.php, and tercih-sihirbazi-*.php now return only an empty SPA shell. Never scrape them. Use only the JSON API under /api/tercih-kilavuz/ (or, as this skill does, yokatlas-py which wraps it). Endpoint and field details: references/api_endpoints.md.

Does NOT Trigger — route these elsewhere

This skill answers "what are the admission/quota/staff numbers for this program or university?" — nothing about an individual scholar's output.

How It Works

The data source

yokatlas-py (MIT, Python ≥3.10; 0.7.0 released 2026-07-23) exposes these as module-level functions search_programs(filters_dict, size=…), get_program(kilavuz_kodu), list_universities(), and — new in 0.7.0 — list_program_groups(), list_cities() and search_netler() (average nets per test section, /api/netler/search); plus a YokAtlasClient / SearchFilters / Program object API. It normalizes Turkish characters (İ/ı, Ş/ş, Ğ/ğ, Ç/ç, Ö/ö, Ü/ü), so "boğaziçi" and "bogazici" both resolve. Full filter and field reference: references/api_endpoints.md.

Name resolution gotcha. universite, program and il are resolved to ONE lookup entry each: exact name first, then the first entry that contains the text, then a close match — otherwise the call fails. A fragment like program="bilgisayar" silently resolves to the group "Bilgisayar Bilimleri" and returns nothing for Boğaziçi; use the full group name ("bilgisayar mühendisliği") or birim_grup_id. Abbreviations such as "odtü" do not resolve ("orta doğu teknik" does). An empty page means "no match for this group", not "no such program" — check the resolved name before reporting.

Pipeline

1. Pick the operation from the request: list universities, search programs,

or fetch one program by its kılavuz kodu (guide code).

1. Build filters. The common SearchFilters fields are puan_turu

(SAY/SÖZ/EA/DİL/TYT), universite, program, il (province), universite_turu (DEVLET/VAKIF), and min_basari_sirasi/max_basari_sirasi for a success-rank window. See references/api_endpoints.md for the full list.

1. Run the helper:

   uv run --with yokatlas-py python \
     skills/turkish-academia/alterlab-yokatlas/scripts/yokatlas_lookup.py \
     search --puan-turu SAY --universite "boğaziçi" --program "bilgisayar mühendisliği" --size 20

Other subcommands:

   # All universities (id + name)
   uv run --with yokatlas-py python .../yokatlas_lookup.py universities

   # One program's multi-year statistics by guide code
   uv run --with yokatlas-py python .../yokatlas_lookup.py program --kod 102210277

The script prints a JSON envelope ({"tool", "operation", "count", "results"}; searches add total_elements, data_year, and a note when nothing matched). If yokatlas-py or the network is unavailable it prints a structured {"error": …, "manual_instructions": …} and exits non-zero — it never fabricates statistics.

1. Read the JSON and report. For each program surface the year, kontenjan,

yerlesen, min_puan, basari_sirasi, and (when asked) the staff counts. Each Program carries up to four years (current + history; on 2026-09-23 current was the 2026 placement year); state which year a number is from — some history years carry only scores, with quota fields empty.

1. Cross-link if the user drifts. If they then ask about a person's CV or

publications, hand off to alterlab-yok-akademik; for theses, alterlab-yok-tez.

Worked Patterns

• Program benchmarking. Search the same program across universite_turu

DEVLET vs VAKIF, then tabulate min_puan / basari_sirasi side by side.

• Student advising. Given a target başarı sırası, filter with

max_basari_sirasi to list programs realistically in reach.

• Institutional research. Fetch a program by kılavuz kodu and report the

staff mix (prof/doc/dou/ogr_gor/ar_gor) and the kontenjan→yerleşen fill rate across the available years.

More query recipes: references/query_recipes.md.

Caveats & Self-Check

• Pin the wrapper. Use yokatlas-py ≥0.6.0 (0.7.0 current); the upstream

JSON API changed once (April 2026) and broke every legacy scraper. If results look malformed, re-verify the package version before reporting; if they are merely empty, check the name-resolution gotcha above first.

• No demographic breakdowns since v0.6.0 (gender / high-school-type splits),

still absent in 0.7.0. Do not promise those fields — only the staff/quota/score fields above (and 0.7.0's nets) are returned.

• Score type matters. A program's min_puan is only meaningful next to its

puan_turu; always report them together.

• Data year. Numbers are historical (latest plus three prior years). Never

imply a figure is "current admissions" without naming its year.

• Did the script reach the network? If it returned an error envelope, say

so and relay the manual_instructions — do not infer numbers from memory.

References

• references/api_endpoints.md — the /api/tercih-kilavuz/ endpoints, the full

SearchFilters field list, enums (puan türü, university type, birim türü), and the returned statistic fields, with the legacy-PHP-dead caveat.

• references/query_recipes.md — worked yokatlas_lookup.py invocations for

benchmarking, advising, and institutional-research questions.

Part of the AlterLab Academic Skills suite.