# YÖK Atlas — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access Turkey's official higher education database via YÖK Atlas. Search and filter universities and degree programs by city, score type, and field of study; retrieve admission statistics, success rankings, quotas, tuition details, graduate exam outcomes, and full university profiles.

**Category:** Education | **Website:** [yokatlas.yok.gov.tr/](https://yokatlas.yok.gov.tr/) | **Docs:** [parse.bot/marketplace/bdd36f43-2790-4426-8c7d-0706890bf033/y-k-atlas-api](https://parse.bot/marketplace/bdd36f43-2790-4426-8c7d-0706890bf033/y-k-atlas-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-y-k-atlas-api-bdd36f43/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_graduate_success

Get graduate success statistics for central exams (TUS, DUS, KPSS, etc.).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `exam_id` | string | Yes | Exam ID: 1=TUS, 4=DUS, 6=KPSS etc. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-y-k-atlas-api-bdd36f43/get_graduate_success \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exam_id":"<string>"}'
```

### get_program_details

Get detailed statistics and info for a specific program (scores, ranks, gender distribution, academic staff, etc.). Program codes can be obtained from get_university_programs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `level` | string | No | Education level: 'lisans' or 'onlisans' |
| `panels` | string | No | Comma-separated panel IDs to fetch (e.g., '1000_1,1000_2'). If not specified, all panels are fetched. |
| `program_code` | string | Yes | ÖSYM program code (e.g., '100110645') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-y-k-atlas-api-bdd36f43/get_program_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"level":"<string>","panels":"<string>","program_code":"<string>"}'
```

### get_university_detail

Get university-level detailed info (name, type, city, website, address, logo). Uses the university ID from list_universities endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `university_id` | string | Yes | University ID from list_universities (e.g., '173499', '100259') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-y-k-atlas-api-bdd36f43/get_university_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"university_id":"<string>"}'
```

### get_university_programs

Get all programs offered by a specific university. Uses the internal YÖK Atlas university code (e.g., 1001 for Bolu Abant İzzet Baysal Üniversitesi). University codes can be retrieved from the list_universities endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `level` | string | No | Education level: 'lisans' (bachelor) or 'onlisans' (associate) |
| `university_id` | string | Yes | YÖK Atlas internal university code (e.g., '1001', '1002') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-y-k-atlas-api-bdd36f43/get_university_programs \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"level":"<string>","university_id":"<string>"}'
```

### list_cities

List all Turkish cities (and some international locations such as KIBRIS, BOSNA-HERSEK) that have universities. City codes can be used as filters in the search_programs endpoint. The list is not paginated.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-y-k-atlas-api-bdd36f43/list_cities \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### list_programs

List all program groups (fields of study) available in the system with their IDs, names, and associated score types. Program group IDs can be used as filters in the search_programs endpoint. The list is not paginated.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-y-k-atlas-api-bdd36f43/list_programs \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### list_universities

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.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-y-k-atlas-api-bdd36f43/list_universities \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search

Global search for universities and programs by keyword.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `term` | string | Yes | Search keyword (e.g., 'bilgisayar', 'tıp') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-y-k-atlas-api-bdd36f43/search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"term":"<string>"}'
```

### search_programs

Search and filter university programs with pagination. Returns detailed program information including admission scores, success ranks, quotas, tuition fees, scholarship status, and more. All filter parameters are optional; omitting all filters returns all programs sorted by success rank ascending. Supports pagination with zero-based page numbers.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_code` | string | No | City code to filter by (from list_cities, e.g. '34' for İstanbul). |
| `direction` | string | No | Sort direction. |
| `page` | integer | No | Zero-based page number for pagination. |
| `program_group_id` | string | No | Program group ID to filter by (from list_programs). |
| `score_type` | string | No | Score type filter. |
| `size` | integer | No | Number of results per page (max observed: 100). |
| `sort_by` | string | No | Field to sort by. |
| `university_id` | string | No | University ID to filter by (from list_universities). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-y-k-atlas-api-bdd36f43/search_programs \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city_code":"<string>","direction":"<string>","page":"<integer>","program_group_id":"<string>","score_type":"<string>","size":"<integer>","sort_by":"<string>","university_id":"<string>"}'
```