alterlab-yokatlas

YÖK Atlas — 土耳其大学专业与招生统计

从 YÖK Atlas（Yükseköğretim Kurulu Atlası — 高等教育委员会专业图谱）获取土耳其任意本科（lisans）或副学士（önlisans）专业的官方专业级统计数据：招生名额、录取人数、最低录取分数、录取排名，以及按职称统计的教职员工人数。它通过维护中的 yokatlas-py 软件包封装了无需密钥的 YÖK Atlas JSON API，因此相同的查询会返回相同结构化记录——无需抓取 HTML，也无需 API 密钥。

这是统计技能。它不会查询某位学者的简历、发表成果或任职单位——这些查询应使用架构独立的 YÖK 系统 alterlab-yok-akademik（参见下方路由表）。

何时使用此技能

用户需要查询 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?

→ 运行 scripts/yokatlas_lookup.py（一个轻量的 yokatlas-py 封装器），读取 JSON，然后以表格形式呈现所需统计数据。务必注明数据年份，并说明数据来自 YÖK Atlas。

土耳其语标准术语（首次出现时附英文释义）

土耳其语	释义	API 字段
kontenjan	招生名额（可录取人数）	kontenjan
yerleşen	录取人数（已入学学生人数）	yerlesen
taban puan	最低录取分数	min_puan
başarı sırası	录取排名（最后一名录取学生的全国排名）	basari_sirasi
puan türü	分数类型（SAY/SÖZ/EA/DİL/TYT）	puan_turu
lisans / önlisans	本科 / 副学士	birim_turu_id 46 / 47
kılavuz kodu	指南代码（专业唯一 ID）	kilavuzKodu

教职员工职称人数以 prof（profesör，教授）、doc（doçent，副教授）、dou（doktor öğretim üyesi，博士教师）、ogr_gor（öğretim görevlisi，讲师）和 ar_gor（araştırma görevlisi，研究助理）字段返回。

⚠️ 端点注意事项（抓取任何内容前请先阅读）

截至 2026 年 4 月，YÖK Atlas 已从服务器渲染的 PHP 迁移至基于 JSON API 的 React SPA。旧版 PHP 端点已失效——lisans.php?y=…、lisans-panel.php 和 tercih-sihirbazi-*.php 现在只会返回空的 SPA 外壳。**切勿抓取这些端点。**只能使用 /api/tercih-kilavuz/ 下的 JSON API（或像本技能一样使用封装了该 API 的 yokatlas-py）。端点和字段详情：references/api_endpoints.md。

不适用 — 请转至以下工具

用户实际需要……	转至
学者的简历、发表成果、项目、指导的论文，或官方任职单位（akademik.yok.gov.tr）	alterlab-yok-akademik
研究生论文（tez）——全文、摘要、原创性／新颖性检查（Ulusal Tez Merkezi）	alterlab-yok-tez
查询某期刊是否被 TR Dizin 收录，或搜索期刊／文章	alterlab-trdizin
DergiPark 上的文章（采集、BibTeX、期刊范围）	alterlab-dergipark
计算副教授资格（doçentlik）资格积分	alterlab-docentlik-eligibility
计算学术激励（akademik teşvik）分数	alterlab-akademik-tesvik
为 TÜBİTAK ARDEB 1001/1002-A 项目搭建申请书框架	alterlab-tubitak-proposal
作者的发表元数据（DOI、引用次数、h 指数）	alterlab-research-lookup / alterlab-openalex

此技能回答的是**“这个专业或大学的录取／招生名额／教职员工人数是多少？”**——不涉及任何学者个人的研究成果。

工作原理

数据源

接口	返回内容
/api/tercih-kilavuz/universiteler	大学列表（{universiteAdi, universiteId}，截至 2026-09-23 共 228 所）
/api/tercih-kilavuz/universite-programlar	专业组列表（{birimGrupId, birimGrupAdi, puanTuru}，共 611 个）——不是各大学的专业列表
/api/tercih-kilavuz/universite-iller	省份（{ilAdi, ilKodu}）
/api/tercih-kilavuz/search	使用 SearchFilters 搜索专业

yokatlas-py（MIT 许可，Python ≥3.10；0.7.0 于 2026-07-23 发布）将这些功能封装为模块级函数：search_programs(filters_dict, size=…)、get_program(kilavuz_kodu)、list_universities()，以及 0.7.0 新增的 list_program_groups()、list_cities() 和 search_netler()（每个考试部分的平均净分，/api/netler/search）；此外还提供 YokAtlasClient / SearchFilters / Program 对象 API。它会规范化土耳其字符（İ/ı、Ş/ş、Ğ/ğ、Ç/ç、Ö/ö、Ü/ü），因此 "boğaziçi" 和 "bogazici" 都能匹配。完整的筛选条件和字段参考：references/api_endpoints.md。

名称解析注意事项。 universite、program 和 il 各自只会解析为一个查找项：优先精确匹配，其次选取第一个包含该文本的项，再尝试近似匹配——否则调用会失败。像 program="bilgisayar" 这样的片段会静默解析为专业组“Bilgisayar Bilimleri”，不会返回 Boğaziçi 的结果；请使用完整组名（"bilgisayar mühendisliği"）或 birim_grup_id。像 "odtü" 这样的缩写无法解析（"orta doğu teknik" 可以）。空结果页表示“该组没有匹配项”，而非“没有这个专业”——报告前请检查解析出的名称。

工作流程

1. 选择操作：根据请求选择列出大学、搜索专业，或按 kılavuz kodu（指南代码）获取某个专业。

2. 构建筛选条件。 常用的 SearchFilters 字段包括 puan_turu（SAY/SÖZ/EA/DİL/TYT）、universite、program、il（省份）、universite_turu（DEVLET/VAKIF），以及用于设置 başarı sırası 区间的 min_basari_sirasi/max_basari_sirasi。完整列表请参阅 references/api_endpoints.md。

3. 运行辅助脚本：

   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
   

   其他子命令：

   # 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
   

   脚本会输出 JSON 封装（{"tool", "operation", "count", "results"}；搜索还会附带 total_elements、data_year，以及无匹配项时的 note）。如果 yokatlas-py 或网络不可用，脚本会输出结构化的 {"error": …, "manual_instructions": …} 并以非零状态码退出——绝不会编造统计数据。

4. 读取 JSON 并汇报。 对于每个专业，请注明年份、kontenjan、yerlesen、min_puan、basari_sirasi，以及（在用户询问时）教职员工人数。每个 Program 最多包含四年的数据（current + history；截至 2026-09-23，current 对应 2026 年录取年份）；请注明数字对应的年份——有些历史年份仅包含分数，名额字段为空。

5. 用户转向其他话题时进行交接。 如果用户接着询问某人的简历或出版物，请转交给 alterlab-yok-akademik；如果询问学位论文，请转交给 alterlab-yok-tez。

示例模式

• 专业对标。 对同一个 program 分别搜索 universite_turu 为 DEVLET 和 VAKIF 的结果，然后并排列出 min_puan / basari_sirasi。
• 学生升学建议。 给定目标 başarı sırası，使用 max_basari_sirasi 筛选，列出实际有机会录取的专业。
• 院校研究。 按 kılavuz kodu 获取专业，并报告教职员工构成（prof/doc/dou/ogr_gor/ar_gor）以及各可用年份的 kontenjan→yerleşen 填报率。

更多查询示例：references/query_recipes.md。

注意事项与自查

• 固定封装版本。 使用 yokatlas-py ≥0.6.0（当前为 0.7.0）；上游 JSON API 曾在 2026 年 4 月变更一次，导致所有旧版抓取器失效。如果结果 格式异常，在报告前重新确认软件包版本；如果结果只是为空，请先检查上文提到的名称解析问题。
• 自 v0.6.0 起不再提供人口统计细分（性别／高中类型细分）， 0.7.0 中仍然没有。不要承诺这些字段——只会返回上文提到的教职员工／招生名额／分数 字段（以及 0.7.0 的净值）。
• 分数类型很重要。 某个专业的 min_puan 只有与其 puan_turu 一并提供才有意义；务必同时报告。
• 数据年份。 数值为历史数据（最新年份及此前三年）。如果不注明年份，绝不要暗示某个数值代表“当前招生”。
• 脚本是否成功访问了网络？ 如果返回了 error 封装对象，请如实说明，并转达 manual_instructions——不要凭记忆推断数值。

参考资料

• references/api_endpoints.md — /api/tercih-kilavuz/ 端点、完整的 SearchFilters 字段列表、枚举（puan türü、大学类型、birim türü）以及 返回的统计字段，并说明旧版 PHP 接口已停用。
• references/query_recipes.md — yokatlas_lookup.py 的示例调用，涵盖基准比较、升学指导和机构研究问题。

AlterLab Academic Skills 套件的一部分。