Gov APIyokatlas.yok.gov.tr ↗
Access Turkey's official higher education atlas via API. Search universities, programs, admission scores, quotas, graduate exam stats, and city-based filters.
What is the Gov API?
The YÖK Atlas API exposes 9 endpoints covering Turkey's complete higher education catalog, from university rosters and program details to admission scores and graduate exam outcomes. Use search_programs to filter programs by city, score type, and field of study with paginated results, or call get_program_details to retrieve per-program statistics including success ranks, gender distribution, academic staff counts, and tuition details.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/55fafd1a-550d-412b-a1c6-91ad9e1aac17/list_universities' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace y-k-atlas-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""YÖK Atlas API - Turkish Higher Education Data
Get your API key from: https://parse.bot/settings
Explore Turkish universities, academic programs, cities, and filter programs
by score type, university, city, or program group.
"""
from parse_apis.yök_atlas_api import YokAtlas, Sort, SortDirection, ScoreType, ProgramNotFound
client = YokAtlas()
# List all universities in the system.
for uni in client.universities.list(limit=5):
print(uni.university_id, uni.name)
# List program groups to find a field of study.
program_group = client.programgroups.list(limit=1).first()
if program_group:
print(program_group.program_group_id, program_group.name, program_group.score_type)
# Search programs sorted by minimum score, filtered to science track.
for prog in client.programs.search(score_type=ScoreType.SAY, sort_by=Sort.MIN_SCORE, direction=SortDirection.DESC, limit=3):
print(prog.university_name, prog.program_name, prog.min_score, prog.success_rank)
# Typed error handling around a search call.
try:
result = client.programs.search(city_code="34", sort_by=Sort.SUCCESS_RANK, limit=2).first()
if result:
print(result.kilavuz_kodu, result.university_name, result.city, result.quota)
except ProgramNotFound as exc:
print(f"No programs found: {exc}")
# List cities to discover available locations.
for city in client.cities.list(limit=5):
print(city.city_code, city.city_name)
print("Exercised: universities.list / programgroups.list / programs.search / cities.list")
List all Turkish universities with their internal IDs and names. Returns the complete roster of universities available in the YÖK Atlas system. The list is not paginated — all universities are returned in a single response.
No input parameters required.
{
"type": "object",
"fields": {
"universities": "array of university objects with university_id and name"
},
"sample": {
"data": {
"universities": [
{
"name": "ABDULLAH GÜL ÜNİVERSİTESİ (KAYSERİ)",
"university_id": 173499
},
{
"name": "ACIBADEM MEHMET ALİ AYDINLAR ÜNİVERSİTESİ (İSTANBUL)",
"university_id": 326654
}
]
},
"status": "success"
}
}About the Gov API
University and Program Discovery
The list_universities endpoint returns every university in the YÖK Atlas system as a single unpaginated array, each entry carrying a university_id and name. Pass a university_id to get_university_programs with an optional level parameter (lisans for bachelor, onlisans for associate) to retrieve all programs at that institution, each with a code, name, and url. For full institution metadata — type, city, website, address, and logo URL — use get_university_detail.
Program Search and Filtering
search_programs is the primary filtering endpoint. It accepts optional parameters for city_code (sourced from list_cities), university_id, program_group_id (sourced from list_programs), and score_type. Results are paginated via zero-based page and size parameters and return fields including university_name, program_name, program_group, faculty, city, and score_type, along with aggregate counts via total_pages and total_elements. The keyword-based search endpoint covers both universities and programs, returning kod, sonuc, etiket, and etiket2 fields useful for resolving codes before deeper lookups.
Program Details and Graduate Outcomes
get_program_details accepts an ÖSYM program_code and an optional comma-separated panels parameter to request specific data panels (e.g., 1000_1,1000_2). Omitting panels returns all available panels, which cover statistics such as admission score ranges, success ranks, quota fill rates, and gender distribution. The get_graduate_success endpoint returns per-university performance tables for centralized post-graduation exams including TUS (medical specialization), DUS (dental specialization), and KPSS (civil service), identified by numeric exam_id.
Reference Lists
list_programs and list_cities return unpaginated reference data: program groups with their associated score_type, and cities including non-mainland locations such as KIBRIS and BOSNA-HERSEK. Both are intended as filter-building lookups for use with search_programs.
The Gov API is a managed, monitored endpoint for yokatlas.yok.gov.tr — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when yokatlas.yok.gov.tr changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official yokatlas.yok.gov.tr API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a university comparison tool using admission scores and quota data from
search_programsfiltered bycity_codeandscore_type - Populate a program-finder app with full field-of-study listings from
list_programsand per-program statistics fromget_program_details - Track graduate exam outcomes (TUS, KPSS, DUS) across universities using
get_graduate_successwith differentexam_idvalues - Display full university profiles including city, type, website, and logo by combining
list_universitiesandget_university_detail - Power an autocomplete search for Turkish university programs using the
searchendpoint'ssonucandetiketfields - Analyze geographic distribution of programs and institutions by cross-referencing
list_citiescity codes withsearch_programsresults - Enumerate all associate and bachelor programs at a given institution by calling
get_university_programswith eachlevelvalue
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does YÖK Atlas provide an official public developer API?+
What does `get_program_details` return, and how do I limit the response to specific data panels?+
details object whose keys are panel names and whose values are table data for that panel — covering stats like admission scores, success ranks, quota fill rates, and gender distribution. Pass a comma-separated list of panel IDs to the panels parameter (e.g., 1000_1,1000_2) to fetch only those panels. Omitting panels fetches all available panels for that program.Does `search_programs` support filtering by both university and city simultaneously?+
search_programs accepts university_id, city_code, program_group_id, and score_type as independent optional filters; you can combine any subset of them in a single request. Results are paginated via page and size and include total_pages and total_elements for iterating through large result sets.Does the API expose historical year-over-year admission score trends for programs?+
get_program_details returns panel-based statistics for a program, which may include prior-year data within its table rows depending on the panel, but there is no endpoint that returns a structured multi-year score history series. You can fork this API on Parse and revise it to add an endpoint that extracts and structures historical score panels explicitly.Are private (vakıf) and state universities both included, and is international student quota data available?+
list_universities and get_university_detail, which returns a type field distinguishing them. International student quota data is not currently exposed as a distinct field in search_programs or get_program_details. You can fork this API on Parse and revise it to surface international quota figures if they are present in program panel data.