Fetch courses for a specific department

Retrieves all courses for a specified department from Stanford ExploreCourses, either from cache if available or from the API. Supports fetching courses for specific academic years and handles caching automatically when a cache directory is specified.

Usage

fetch_department_courses(name, year = NULL, cache_dir = NULL)

Arguments

name

Character string. Department code (e.g., "CS"). Must be a single, non-empty string. If multiple codes provided, only the first is used.

year

Character string. Optional academic year in YYYYYYYY format (e.g., "20232024"). If NULL, fetches data for the current academic year.

cache_dir

Character string. Optional path to cache directory. If provided, the function will:

• Try to read existing course data from cache

• Cache fresh API data when cache miss occurs If NULL, always fetches fresh data from the API.

Value

A tibble (data frame) containing course information with columns:

• objectID: Unique course identifier

• year: Academic year

• subject: Department code

• code: Course number

• title: Course title

• description: Course description

• units_min: Minimum units

• units_max: Maximum units

• department: Department code of the course

• term: Academic term (e.g., "Autumn", "Winter")

• term_id: Numeric term identifier

• section_number: Section identifier

• component: Course component type (e.g., "LEC", "DIS", "LAB")

• class_id: Unique identifier for the section

• current_class_size: Current enrollment

• max_class_size: Maximum enrollment capacity

• Schedule information:

  • days: Days of the week (e.g., "Mon, Wed, Fri")

  • start_time: Start time of the class

  • end_time: End time of the class

  • location: Class location/room

• Instructor information:

  • instructors: Combined instructor information with roles

  • instructor_names: Names of instructors

  • instructor_sunets: SUNet IDs of instructors

  • instructor_roles: Roles of instructors

Returns NULL if no courses found.

Details

The function follows this process:

1. Input validation:

   • Ensures single department code

   • Validates code format and content

2. Data retrieval:

   • Checks cache if cache_dir provided

   • Fetches from API on cache miss

   • Caches new data if applicable

3. Data processing:

   • Parses XML into structured format

   • Validates course data exists

Warning handlers

Warning message will be shown if:

• Multiple department codes provided

• No courses found for department

Error Handling

• Invalid department code (empty or non-string)

• API fetch failures

• Cache operation failures

• XML processing errors

See also

• fetch_departments() for getting list of valid department codes

• fetch_all_courses() for fetching courses from multiple departments

• validate_academic_year() for year format details

Examples

if (FALSE) { # \dontrun{
# Fetch current year's CS courses
cs_courses <- fetch_department_courses("CS")

# Fetch specific academic year
cs_courses_2023 <- fetch_department_courses(
  name = "CS",
  year = "20232024"
)

# Fetch with caching enabled
cs_courses <- fetch_department_courses(
  name = "CS",
  cache_dir = "course_cache"
)

# Handle empty results
courses <- fetch_department_courses("DEPT")
if (!is.null(courses)) {
  # Process courses
}

# Find all courses taught by a specific instructor
cs_courses %>%
  dplyr::filter(grepl("Smith", instructor_names))

# Get all lecture sections
lectures <- cs_courses %>%
  dplyr::filter(component == "LEC")
} # }