Package 'tezr'

Title: Access Thesis Metadata from Turkiye's National Thesis Center
Description: Retrieve, parse, cache, and analyze thesis metadata from the Council of Higher Education's National Thesis Center (Ulusal Tez Merkezi) at <https://tez.yok.gov.tr>. Supports basic, advanced, and detailed search. Also supports thesis detail retrieval, lookup tables, adaptive pagination for capped search results, and aggregate statistics for retrieval checks.
Authors: Emrah Er [aut, cre]
Maintainer: Emrah Er <[email protected]>
License: MIT + file LICENSE
Version: 0.1.0.9000
Built: 2026-10-17 08:32:19 UTC
Source: https://github.com/emraher/tezr

Help Index


Clear the cache

Description

Removes cached search results, thesis details, and lookup data from memory.

Usage

cache_clear(what = c("all", "searches", "details", "lookups"))

Arguments

what

Character. What to clear: "all", "searches", "details", or "lookups". Default is "all".

Value

Invisible NULL

See Also

Other cache functions: cache_config(), cache_info()

Examples

# Clear everything
cache_clear()

# Clear only search results
cache_clear("searches")

# Clear only thesis details
cache_clear("details")
info <- cache_info()
info[c("search_count", "detail_count")]
#> $search_count
#> [1] 0
#>
#> $detail_count
#> [1] 0

Configure cache behavior

Description

Controls whether search results and thesis details are cached in memory during the R session. Caching can significantly speed up repeated queries.

Usage

cache_config(enable = TRUE, search_ttl = 3600, detail_ttl = NULL)

Arguments

enable

Logical. Enable caching? Default TRUE.

search_ttl

Numeric. Search result TTL (time-to-live) in seconds. NULL means cache lives for entire session. Default is 3600 (1 hour).

detail_ttl

Numeric. Detail page TTL in seconds. NULL means cache lives for entire session. Default is NULL (session).

Value

Invisible NULL

See Also

Other cache functions: cache_clear(), cache_info()

Examples

# Disable caching entirely
cache_config(enable = FALSE)

# Enable with 30-minute TTL for searches
cache_config(enable = TRUE, search_ttl = 1800)
info <- cache_info()
info[c("enabled", "search_ttl")]
#> $enabled
#> [1] TRUE
#>
#> $search_ttl
#> [1] 1800

# Cache details forever (until session ends)
cache_config(detail_ttl = NULL)

Get cache statistics

Description

Returns information about the current cache state, including number of cached items and configuration settings.

Usage

cache_info()

Value

A list with cache statistics:

  • enabled - Whether caching is enabled

  • search_count - Number of cached search results

  • range_count - Number of cached year-range searches

  • detail_count - Number of cached thesis details

  • search_ttl - Search cache TTL in seconds (NULL = session)

  • detail_ttl - Detail cache TTL in seconds (NULL = session)

See Also

Other cache functions: cache_clear(), cache_config()

Examples

cache_info()

Get detailed information about a thesis

Description

Retrieves the full details of one or more theses from the Turkish National Thesis Center using encoded IDs from search results.

Usage

detail(detail_id, progress = TRUE, ...)

Arguments

detail_id

Character vector. Encoded thesis detail identifier(s) from the detail_id column of search results. Treat these values as opaque. They may contain one or more portal identifiers depending on the current National Thesis Center markup.

progress

Logical. Show text progress updates when fetching multiple theses? Default is TRUE.

...

Reserved for internal use.

Value

A tibble with thesis details (one row per thesis). Columns (in order):

  • thesis_no - Thesis number

  • title_original - Original title

  • title_translation - Title translation when available

  • author - Author name

  • advisor - Advisor name and title

  • co_advisor - Co-advisor name(s). Multiple names are semicolon-separated, and absent values are NA.

  • university - University name

  • institute - Institute name

  • division - Division name

  • year - Year

  • pages - Number of pages

  • thesis_type_tr - Thesis type in Turkish, such as "Doktora" or "Yüksek Lisans"

  • thesis_type_en - Thesis type in English, such as "Doctorate" or "Master's"

  • language_tr - Language in Turkish, such as "Türkçe" or "İngilizce"

  • language_en - Language in English (e.g., "Turkish", "English")

  • subject_tr - Turkish subject classifications, semicolon-separated when multiple

  • subject_en - English subject classifications, semicolon-separated when multiple

  • abstract_original - Abstract in the thesis's original language when available

  • abstract_translation - Translated abstract when available

  • keywords_tr - Turkish keywords (includes keywords from index field)

  • keywords_en - English keywords (includes keywords from index field)

  • access_status - Access status (open/restricted)

  • pdf_url - URL to download PDF (if available)

  • detail_url - URL to the thesis detail page

Examples

# Search for theses
results <- search_basic("panel veri")

# Get details for a single thesis
thesis_details <- detail(results$detail_id[1])
dplyr::glimpse(thesis_details)
#> Rows: 1
#> Columns: 24
#> $ thesis_no            <chr> "393353"
#> $ title_original       <chr> "Enerji piyasasi duzenlemeleri..."
#> $ author               <chr> "ISIL SIRIN SELCUK CAKMAK"
#> $ university           <chr> "Ankara Universitesi"
#> $ thesis_type_en       <chr> "Doctorate"
#> $ abstract_translation <chr> "This thesis consists of..."

# Get details for multiple theses (batch)
all_details <- detail(detail_id = results$detail_id)

# Without progress updates
all_details <- detail(detail_id = results$detail_id, progress = FALSE)

List all available disciplines

Description

Returns all disciplines (Bilim Dalı values) in the National Thesis Center database. Turkish: Bilim Dalı

Usage

list_disciplines()

Value

A tibble with two columns:

  • name - Character. Discipline name

  • id - Character. Internal API identifier

See Also

Other lookup functions: list_divisions(), list_institutes(), list_subjects(), list_universities()

Examples

disciplines <- list_disciplines()
head(disciplines)
#> # A tibble: 6 x 2
#>   name                         id
#>   <chr>                        <chr>
#> 1 ACIK DENIZ YAPILARI          1
#> 2 ADLI BILIMLER                2

List all available divisions

Description

Returns all divisions (Anabilim Dalı values) in the National Thesis Center database. Turkish: Anabilim Dalı (ABD)

Usage

list_divisions()

Value

A tibble with two columns:

  • name - Character. Division name

  • id - Character. Internal API identifier

See Also

Other lookup functions: list_disciplines(), list_institutes(), list_subjects(), list_universities()

Examples

divisions <- list_divisions()
head(divisions)
#> # A tibble: 6 x 2
#>   name                         id
#>   <chr>                        <chr>
#> 1 ACIL TIP ANABILIM DALI       1
#> 2 ADLI BILISIM ANABILIM DALI   2

List all available institutes

Description

Returns all institutes in the National Thesis Center database. Turkish: Enstitü

Usage

list_institutes()

Value

A tibble with two columns:

  • name - Character. Institute name

  • id - Character. Internal API identifier

See Also

Other lookup functions: list_disciplines(), list_divisions(), list_subjects(), list_universities()

Examples

insts <- list_institutes()
head(insts)
#> # A tibble: 6 x 2
#>   name                       id
#>   <chr>                      <chr>
#> 1 ADLI TIP ENSTITUSU         1
#> 2 AFET YONETIMI ENSTITUSU    2

List all available subjects

Description

Returns all subjects in the National Thesis Center database. Turkish: Konu

Usage

list_subjects()

Value

A tibble with three columns:

  • name_tr - Character. Turkish subject name

  • name_en - Character. English subject name

  • id - Character. Internal API identifier

See Also

Other lookup functions: list_disciplines(), list_divisions(), list_institutes(), list_universities()

Examples

subjects <- list_subjects()
head(subjects)
#> # A tibble: 6 x 3
#>   name_tr    name_en      id
#>   <chr>      <chr>        <chr>
#> 1 Ekonomi    Economics    115
#> 2 Ekonometri Econometrics 116

List all available universities

Description

Returns all universities in the National Thesis Center database. Turkish: Üniversite

Usage

list_universities()

Value

A tibble with two columns:

  • name - Character. University name

  • id - Character. Internal API identifier

See Also

Other lookup functions: list_disciplines(), list_divisions(), list_institutes(), list_subjects()

Examples

unis <- list_universities()
head(unis)
#> # A tibble: 6 x 2
#>   name                              id
#>   <chr>                             <chr>
#> 1 ABDULLAH GUL UNIVERSITESI         384
#> 2 ACIBADEM MEHMET ALI AYDINLAR ...  361

Configure request behavior

Description

Sets package-level request options. tezr identifies itself with a package-specific user agent by default. You can override that header when required by a network policy or by the National Thesis Center portal.

Usage

request_config(user_agent = NULL, verbose = NULL, reset = FALSE)

Arguments

user_agent

Character. Optional user agent to send with HTTP requests.

verbose

Logical. Show informational request messages?

reset

Logical. Reset request options to package defaults before applying other arguments.

Details

Informational messages are shown by default. Set verbose = FALSE to silence progress and success messages. Warnings and errors are still shown.

You can also set TEZR_USER_AGENT and TEZR_VERBOSE before starting R. Explicit R options take precedence over environment variables.

Value

Invisible list with the active request configuration.

Examples

# Silence progress messages for the current R session
cfg <- request_config(verbose = FALSE)
cfg$verbose
#> [1] FALSE

# Set a custom user agent for an institutional network policy
cfg <- request_config(user_agent = "[email protected]")
cfg$user_agent
#> [1] "[email protected]"

# Return to package defaults
request_config(reset = TRUE)

Advanced search of the Turkiye's National Thesis Center

Description

Keyword-based search with common filter options. Similar to basic search but adds year filtering, language, group, institution, and status filters. Limited to 2000 results per request (server limit). For more results or field-specific searches, use search_detailed.

Usage

search_advanced(
  keyword,
  search_field = c("title", "all", "author", "supervisor", "subject", "index",
    "abstract"),
  match_type = c("exact", "contains"),
  year_start = NULL,
  year_end = NULL,
  group = c("all", "science", "social", "medical"),
  university = NULL,
  university_id = NULL,
  thesis_type = c("all", "masters", "phd", "medical_specialty", "arts", "dentistry",
    "medical_sub", "pharmacy"),
  institute = NULL,
  institute_id = NULL,
  language = NULL,
  access_type = c("all", "open", "restricted"),
  status = c("approved", "all", "in_preparation"),
  max_search_results = 2000,
  ignore_cache = FALSE
)

Arguments

keyword

Character. A single search term.

search_field

Character. The field to search in. One of "title", "author", "supervisor", "subject", "index", "abstract", or "all". Default is "title" (matches the web advanced search form).

match_type

Character. Keyword matching strategy. One of "exact" (matches the keyword as entered) or "contains" (substring match). Default is "exact".

year_start

Integer. Start year (optional).

year_end

Integer. End year (optional).

group

Character. Group filter. One of "all", "science" (Fen), "social" (Sosyal), "medical" (Tıp). Default is "all".

university

Character. University name (optional). If provided without university_id, the ID is looked up automatically.

university_id

Integer. University ID (optional). Use this to skip lookup and match the "Choose" behavior in the web form.

thesis_type

Character. Type of thesis. One of "all", "masters", "phd", "medical_specialty", "arts", "dentistry", "medical_sub", "pharmacy". Default is "all".

institute

Character. Institute name (optional). If provided without institute_id, the ID is looked up automatically.

institute_id

Integer. Institute ID (optional). Use this to skip lookup and match the "Choose" behavior in the web form.

language

Integer language ID or character label (e.g., "tr", "en", "Turkish", "İngilizce").

access_type

Character. Access type. One of "all", "open", "restricted". Default is "all".

status

Character. Thesis status. One of "all", "approved", "in_preparation". Default is "approved".

max_search_results

Maximum results to return. Default is 2000 (server limit per query). Use higher values or Inf to paginate and retrieve more results via year-range splitting.

ignore_cache

Logical. If TRUE, bypass cached search/range results and fetch fresh data from the server.

Details

The YOK portal's advanced search form supports up to three keyword rows combined with Boolean operators (AND, OR, NOT), each targeting a different field. This function exposes only the first keyword row. R packages that interface with academic databases, such as rentrez (PubMed) and europepmc (Europe PMC), pass Boolean logic as a single query string (e.g., "term1 AND term2"). The YOK portal does not accept free-form Boolean strings; it uses structured form fields for each keyword row, making that pattern inapplicable here.

For equivalent results:

  • AND across fields: use search_detailed with its field-specific parameters (title, author, supervisor, etc.).

  • OR: run separate searches and combine with dplyr::bind_rows() |> dplyr::distinct().

  • NOT: run both searches and exclude with dplyr::anti_join().

Value

A tibble containing thesis records (same structure as search_basic).

See Also

Other search functions: search_basic(), search_detailed()

Examples

# Keyword search with year filter
climate <- search_advanced(
  keyword = "iklim değişikliği",
  year_start = 2015
)
dplyr::glimpse(climate)
#> Rows: 184
#> Columns: 13
#> $ thesis_no      <chr> "942101", "931450", "918276", ...
#> $ title_original <chr> "Iklim degisikligi...", ...
#> $ university     <chr> "Ankara Universitesi", ...
#> $ year           <int> 2025, 2024, 2024, ...
#> $ thesis_type_en <chr> "Master", "Doctorate", "Master", ...

# Search science theses only
ml <- search_advanced(
  keyword = "makine öğrenmesi",
  group = "science",
  thesis_type = "phd"
)

# Search in-preparation theses
ongoing <- search_advanced(
  keyword = "ekonometri",
  status = "in_preparation"
)

# Filter by university/institute (same fields as web advanced form)
odtu <- search_advanced(
  keyword = "yapay zeka",
  university = "Orta Doğu Teknik Üniversitesi",
  institute = "Fen Bilimleri Enstitüsü"
)

# Get all available results (auto-paginate)
all_climate <- search_advanced(
  keyword = "iklim değişikliği",
  max_search_results = Inf
)

Search the Turkiye's National Thesis Center

Description

Searches the Turkiye's National Thesis Center (Ulusal Tez Merkezi) database and returns matching thesis records.

Usage

search_basic(
  keyword,
  search_field = c("all", "title", "author", "supervisor", "subject", "index",
    "abstract", "thesis_no"),
  access_type = c("all", "open", "restricted"),
  thesis_type = c("all", "masters", "phd", "medical_specialty", "arts", "dentistry",
    "medical_sub", "pharmacy"),
  max_search_results = 2000,
  ignore_cache = FALSE
)

Arguments

keyword

Character. The search term(s).

search_field

Character. The field to search in. One of "title", "author", "supervisor", "subject", "index", "abstract", "all", or "thesis_no". Default is "all".

access_type

Character. Access type filter. One of "all", "open", or "restricted". Default is "all".

thesis_type

Character. Type of thesis to search for. One of "all", "masters", "phd", "medical_specialty", "arts", "dentistry", "medical_sub", or "pharmacy". Default is "all".

max_search_results

Maximum results to return. Default is 2000 (server limit per query). Set to Inf to automatically delegate to search_advanced for pagination when results exceed 2000.

ignore_cache

Logical. If TRUE, bypass cached search/range results and fetch fresh data from the server.

Details

Basic search returns up to 2000 results per query (YOK server limit). When results exceed 2000 and max_search_results > 2000, the search delegates to search_advanced which paginates via year-range splitting to retrieve all results. With the default max_search_results = 2000, a warning is issued suggesting max_search_results = Inf.

Value

A tibble containing thesis records with columns:

  • thesis_no - Unique thesis identifier

  • title_original - Original title

  • title_translation - Title translation when available

  • author - Author name

  • university - University name

  • year - Year of thesis

  • thesis_type_tr - Type of thesis in Turkish

  • thesis_type_en - Type of thesis in English

  • language_tr - Thesis language in Turkish

  • language_en - Thesis language in English

  • subject_tr - Turkish subject classification

  • subject_en - English subject classification

  • detail_id - ID for fetching details

See Also

Other search functions: search_advanced(), search_detailed()

Examples

# Search for theses (returns up to 2000 results)
search_results <- search_basic("hanehalkı")
dplyr::glimpse(search_results)
#> Rows: 2,000
#> Columns: 13
#> $ thesis_no         <chr> "967755", "975988", "955779", ...
#> $ title_original    <chr> "Parasal aktarim mekanizmasi...", ...
#> $ author            <chr> "PERIHAN EZGI BALLI", ...
#> $ university        <chr> "Bandirma Onyedi Eylul Universitesi", ...
#> $ year              <int> 2025, 2025, 2025, ...
#> $ detail_id         <chr> "TCKf4ksTOVsOBqUcPYMKWQ", ...

# Search for PhD theses by a specific author
search_results <- search_basic(
  "Nilay Ünsal",
  search_field = "author",
  thesis_type = "masters"
)

# Search for open access theses
search_results <- search_basic("tarım", access_type = "open")

# Get all results (auto-delegates to advanced search for pagination)
all_results <- search_basic("hanehalkı", max_search_results = Inf)

Detailed search of the Turkiye's National Thesis Center

Description

Searches with detailed field-specific filter options. When total results exceed 2000 (server limit), automatically paginates using year ranges to retrieve all results.

Usage

search_detailed(
  university = NULL,
  university_id = NULL,
  thesis_type = "all",
  year_start = NULL,
  year_end = NULL,
  institute = NULL,
  institute_id = NULL,
  access_type = "all",
  group = "all",
  thesis_no = NULL,
  division = NULL,
  division_id = NULL,
  status = "approved",
  title = NULL,
  discipline = NULL,
  discipline_id = NULL,
  language = NULL,
  author = NULL,
  subject = NULL,
  supervisor = NULL,
  keyword = NULL,
  abstract = NULL,
  max_search_results = 2000,
  ignore_cache = FALSE
)

Arguments

university

University name (optional). Accepts character vector for multiple universities.

university_id

University ID (optional). If provided, lookup by university is skipped.

thesis_type

Type(s) of thesis. Default is "all". Accepts character vector for multiple types: "all", "masters", "phd", "medical_specialty", "arts", "dentistry", "medical_sub", "pharmacy". Multiple values will trigger separate searches that are combined.

year_start

Start year (optional). Used for pagination when results > 2000.

year_end

End year (optional). Used for pagination when results > 2000.

institute

Institute name (optional). Accepts character vector for multiple institutes.

institute_id

Institute ID (optional). If provided, lookup by institute is skipped.

access_type

Access type. Default is "all". Accepts character vector for multiple access types: "all", "open", "restricted". Multiple values will trigger separate searches that are combined.

group

Group filter. One of "all", "science", "social", or "medical". Default is "all".

thesis_no

Thesis number to search for (optional). Accepts character vector for multiple thesis numbers.

division

Division name (optional). Accepts character vector for multiple divisions.

division_id

Division ID (optional). If provided, lookup by division is skipped.

status

Character. Thesis status filter. One of "approved", "all", "in_preparation". Default is "approved".

title

Title to search for (optional). Accepts character vector for multiple titles.

discipline

Discipline name (optional). Accepts character vector for multiple disciplines.

discipline_id

Discipline ID (optional). If provided, lookup by discipline is skipped.

language

Integer language ID or character label (e.g., "tr", "en", "Turkish", "İngilizce"). Accepts a character vector for multiple languages.

author

Author name (optional). Accepts character vector for multiple authors.

subject

Subject (Konu) name (optional). Accepts character vector for multiple subjects.

supervisor

Supervisor name (optional). Accepts character vector for multiple supervisors.

keyword

Keyword text (Dizin) to search (optional). Accepts character vector for multiple keywords.

abstract

Abstract text to search (optional). Accepts character vector for multiple abstracts.

max_search_results

Maximum results to return. Default is 2000 (server limit per query). Use higher values or Inf to get all available results via automatic pagination.

ignore_cache

Logical. If TRUE, bypass cached search/range results and fetch fresh data from the server.

Details

The YOK web portal accepts only a single value per filter field. This function extends beyond the portal by accepting vector-valued parameters for most fields. Multiple values are expanded into separate API calls, and the results are combined and deduplicated by thesis number.

When the total result count exceeds 2000 and no year range is specified, the function automatically uses 1959-present as the year range and paginates to retrieve all results.

Value

A tibble containing thesis records with columns:

  • thesis_no - Unique thesis identifier

  • title_original - Original title

  • title_translation - Title translation when available

  • author - Author name

  • university - University name

  • year - Year of thesis

  • thesis_type_tr - Type of thesis in Turkish

  • thesis_type_en - Type of thesis in English

  • language_tr - Thesis language in Turkish

  • language_en - Thesis language in English

  • subject_tr - Turkish subject classification

  • subject_en - English subject classification

  • detail_id - ID for fetching details

See Also

Other search functions: search_advanced(), search_basic()

Examples

# Field-specific search with year filter
climate <- search_detailed(
  title = "iklim değişikliği",
  year_start = 2015,
  year_end = 2024
)
head(climate)
#> # A tibble: 6 x 13
#>   thesis_no title_original author university year thesis_type_en detail_id
#>   <chr>     <chr>          <chr>  <chr>      <int> <chr>          <chr>
#> 1 967755    Iklim degis... AYSE   Ankara...  2024 Master         TCKf...
#> 2 955779    Iklim polit... MEHMET Istanbul...2023 Doctorate      xSXE...

# Title search with university filter
ml_theses <- search_detailed(
  title = "makine öğrenmesi",
  university = "Orta Doğu Teknik Üniversitesi",
  thesis_type = "phd"
)

# Search by university and division
search_results <- search_detailed(
  university = "Ankara Üniversitesi",
  division = "İktisat Ana Bilim Dalı",
  year_start = 2020,
  year_end = 2023
)

# Get ALL results for a subject (auto-paginates if > 2000)
all_econ <- search_detailed(subject = "Ekonometri", max_search_results = Inf)

# Search for a specific supervisor's theses
search_results <- search_detailed(supervisor = "Hasan Şahin")

# Search across multiple universities (automatically expands)
search_results <- search_detailed(
  university = c("Ankara Üniversitesi", "İstanbul Üniversitesi"),
  subject = "Ekonomi"
)

# Search multiple disciplines within a subject
search_results <- search_detailed(
  subject = "Ekonomi",
  discipline = c("İktisat", "Maliye", "Ekonometri")
)

# Search for multiple specific thesis numbers
search_results <- search_detailed(
  thesis_no = c("123456", "234567", "345678")
)

# Search for multiple titles
search_results <- search_detailed(
  title = c("Ekonometri", "Zaman Serileri")
)

# Search for multiple languages
search_results <- search_detailed(
  subject = "Ekonomi",
  language = c("tr", "en")
)

# Search for multiple thesis types
search_results <- search_detailed(
  subject = "Ekonomi",
  thesis_type = c("phd", "masters")
)

# Search for multiple access types
search_results <- search_detailed(
  subject = "Makine Mühendisliği",
  access_type = c("open", "restricted")
)

# Complex multi-parameter search
search_results <- search_detailed(
  author = c("Ahmet Yılmaz", "Mehmet Demir"),
  university = c("Ankara Üniversitesi", "İstanbul Üniversitesi"),
  year_start = 2020
)

Get thesis statistics by subject

Description

Get thesis statistics by subject

Usage

stats_subjects()

Value

A tibble containing thesis counts per subject and type.

See Also

Other statistics functions: stats_types(), stats_universities(), stats_years()

Examples

stats <- stats_subjects()
head(stats)
#> # A tibble: 6 x 8
#>   subject   yuksek_lisans doktora toplam
#>   <chr>             <int>   <int>  <int>
#> 1 Ekonomi           21142    5842  26984

Get thesis statistics by type

Description

Get thesis statistics by type

Usage

stats_types()

Value

A tibble containing total thesis counts per type.

See Also

Other statistics functions: stats_subjects(), stats_universities(), stats_years()

Examples

stats <- stats_types()
stats
#> # A tibble: 1 x 4
#>   yuksek_lisans doktora tipta_uzmanlik sanatta_yeterlik
#>           <dbl>   <dbl>           <dbl>            <dbl>
#> 1        721384  178264           90030             2395

Get thesis statistics by university

Description

Get thesis statistics by university

Usage

stats_universities()

Value

A tibble containing thesis counts per university and type.

See Also

Other statistics functions: stats_subjects(), stats_types(), stats_years()

Examples

stats <- stats_universities()
head(stats)
#> # A tibble: 6 x 10
#>   university yuksek_lisans doktora toplam
#>   <chr>              <int>   <int>  <int>
#> 1 Ankara Univ...     32542   12310  44852

Get thesis statistics by year

Description

Get thesis statistics by year

Usage

stats_years()

Value

A tibble containing thesis counts per year and type.

See Also

Other statistics functions: stats_subjects(), stats_types(), stats_universities()

Examples

stats <- stats_years()
tail(stats)
#> # A tibble: 6 x 4
#>    year yuksek_lisans doktora toplam
#>   <int>         <int>   <int>  <int>
#> 1  2025         22615    4416  27031