Get Timetable Data

Retrieve complete timetable data for a specific timetable by ID. This endpoint returns all timetable information including subjects, teachers, classes, rooms, lessons, and lesson units (schedule data).

Endpoint

GET /api/v1/timetables/{id}

Authentication

This endpoint requires authentication. Include your API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Request

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The timetable ID obtained from the list timetables endpoint

Headers

Header	Value	Required
Authorization	Bearer YOUR_API_KEY	Yes
Content-Type	application/json	Yes

Response

Success Response

Status Code: 200 OK

{
  "success": true,
  "data": {
    "id": "tt_67890",
    "name": "Term 1 2025 Timetable",
    "orgId": "org_12345",
    "schedulingMode": "standard",
    "basicInfo": {
      "name": "Term 1 2025 Timetable",
      "description": "Main timetable for the first term",
      "academicSession": {
        "name": "2025-26",
        "startDate": "2025-04-01T00:00:00.000Z",
        "endDate": "2026-03-31T00:00:00.000Z"
      }
    },
    "bellSchedule": {
      "scheduleType": "weekly",
      "cycleLength": 1,
      "name": "Default Schedule",
      "dayConfigurations": [
        {
          "id": "dconf_abc123",
          "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
          "weekIndex": null,
          "periods": [
            {
              "id": "prd_001",
              "name": "Period 1",
              "start_time": "08:00",
              "end_time": "08:45"
            },
            {
              "id": "prd_002",
              "name": "Period 2",
              "start_time": "08:45",
              "end_time": "09:30"
            },
            {
              "id": "prd_003",
              "name": "Period 3",
              "start_time": "09:30",
              "end_time": "10:15"
            },
            {
              "id": "prd_004",
              "name": "Period 4",
              "start_time": "10:30",
              "end_time": "11:15"
            }
          ],
          "breaks": [
            {
              "id": "brk_001",
              "name": "Short Break",
              "start_time": "10:15",
              "end_time": "10:30",
              "followsPeriodIndex": 2
            },
            {
              "id": "brk_002",
              "name": "Lunch Break",
              "start_time": "12:30",
              "end_time": "13:15",
              "followsPeriodIndex": 5
            }
          ]
        }
      ]
    },
    "cycleConfig": null,
    "subjects": [
      {
        "id": "math_001",
        "resourceId": "res_sub_001",
        "name": "Mathematics",
        "shortName": "Math",
        "color": "#FF5733"
      },
      {
        "id": "eng_001",
        "resourceId": "res_sub_002",
        "name": "English",
        "shortName": "Eng",
        "color": "#33FF57"
      }
    ],
    "teachers": [
      {
        "id": "teacher_001",
        "memberId": "mem_001",
        "name": "John Smith",
        "shortName": "J.Smith",
        "color": "#3357FF",
        "maxPeriods": null
      },
      {
        "id": "teacher_002",
        "memberId": "mem_002",
        "name": "Sarah Johnson",
        "shortName": "S.Johnson",
        "color": "#FF33F5",
        "maxPeriods": 30
      }
    ],
    "classes": [
      {
        "id": "class_9a",
        "resourceId": "res_cls_001",
        "name": "Grade 9A",
        "shortName": "9A",
        "color": "#F5FF33",
        "classTeacher": "teacher_001"
      },
      {
        "id": "class_9b",
        "resourceId": "res_cls_002",
        "name": "Grade 9B",
        "shortName": "9B",
        "color": "#33FFF5",
        "classTeacher": "teacher_002"
      }
    ],
    "rooms": [
      {
        "id": "room_101",
        "resourceId": "res_room_001",
        "name": "Mathematics Room 1",
        "shortName": "M101",
        "color": "#FF5733",
        "capacity": 40,
        "buildingName": "Main Building",
        "groupName": "Math Rooms"
      },
      {
        "id": "room_102",
        "resourceId": "res_room_002",
        "name": "English Room 1",
        "shortName": "E101",
        "color": "#33FF57",
        "capacity": 35,
        "buildingName": "Language Block",
        "groupName": null
      }
    ],
    "lessons": [
      {
        "id": "lesson_001",
        "teacherIds": ["teacher_001"],
        "classIds": ["class_9a"],
        "subjectIds": ["math_001"],
        "roomIds": ["room_101"],
        "roomGroupName": null,
        "groups": []
      },
      {
        "id": "lesson_002",
        "teacherIds": ["teacher_002"],
        "classIds": ["class_9b"],
        "subjectIds": ["eng_001"],
        "roomIds": ["room_102"],
        "roomGroupName": null,
        "groups": []
      }
    ],
    "lessonUnits": [
      {
        "id": "unit_001",
        "lessonId": "lesson_001",
        "day": "Monday",
        "weekIndex": null,
        "periodIndex": 0,
        "length": 1,
        "classIds": ["class_9a"],
        "subjectIds": ["math_001"],
        "teacherIds": ["teacher_001"],
        "roomIds": ["room_101"],
        "groups": [],
        "locked": false,
        "lockReason": null,
        "sectionIds": null,
        "studentIds": null
      },
      {
        "id": "unit_002",
        "lessonId": "lesson_002",
        "day": "Monday",
        "weekIndex": null,
        "periodIndex": 1,
        "length": 1,
        "classIds": ["class_9b"],
        "subjectIds": ["eng_001"],
        "teacherIds": ["teacher_002"],
        "roomIds": ["room_102"],
        "groups": [],
        "locked": true,
        "lockReason": "user_fixed",
        "sectionIds": null,
        "studentIds": null
      },
      {
        "id": "unit_003",
        "lessonId": "lesson_001",
        "day": null,
        "weekIndex": null,
        "periodIndex": null,
        "length": 1,
        "classIds": ["class_9a"],
        "subjectIds": ["math_001"],
        "teacherIds": ["teacher_001"],
        "roomIds": [],
        "groups": [],
        "locked": false,
        "lockReason": null,
        "sectionIds": null,
        "studentIds": null
      }
    ],
    "status": "published",
    "createdAt": "2025-01-15T08:00:00.000Z",
    "updatedAt": "2025-01-20T14:30:00.000Z"
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Response Fields

Root Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
data	object	The timetable data
timestamp	string	ISO timestamp of the API response

Timetable Data Fields

Field	Type	Description
id	string	Unique timetable identifier
name	string	Human-readable timetable name
orgId	string	Organization identifier
schedulingMode	string	Either standard or student-level
basicInfo	object	Basic information about the timetable
bellSchedule	object	Bell schedule configuration with periods, breaks, and days
cycleConfig	object	Cycle configuration for multi-week schedules (null if not used)
subjects	array	Array of subject objects
teachers	array	Array of teacher objects
classes	array	Array of class objects
rooms	array	Array of room objects
lessons	array	Array of lesson definitions (what to schedule)
lessonUnits	array	Array of lesson unit placements (scheduled and unscheduled)
status	string	Timetable status (draft or published)
createdAt	string	ISO timestamp when timetable was created
updatedAt	string	ISO timestamp when timetable was last updated

Basic Info Object

Field	Type	Description
name	string	Timetable name
description	string	Optional timetable description
academicSession	object	Academic session details (name, startDate, endDate)

Bell Schedule Object

Field	Type	Description
scheduleType	string	Type of schedule: weekly, cyclic, or fixed
cycleLength	number	Number of weeks in the cycle (1 for weekly)
name	string	Name of the bell schedule
dayConfigurations	array	Array of day configuration objects

Day Configuration Object

Field	Type	Description
id	string	Unique identifier for this day configuration
days	array	Array of day names (e.g., ["Monday", "Tuesday"])
weekIndex	number	Week index for multi-week schedules (null for all weeks)
periods	array	Array of period objects with id, name, start_time, end_time
breaks	array	Array of break objects with id, name, start_time, end_time, followsPeriodIndex

Subject Object

Field	Type	Description
id	string	Unique subject identifier
resourceId	string	Reference to organization-level resource
name	string	Full subject name
shortName	string	Abbreviated subject name
color	string	Subject display color (hex)

Teacher Object

Field	Type	Description
id	string	Unique teacher identifier
memberId	string	Reference to organization member
name	string	Full teacher name
shortName	string	Abbreviated teacher name
color	string	Teacher display color (hex)
maxPeriods	number	Maximum periods per cycle (null if not limited)

Class Object

Field	Type	Description
id	string	Unique class identifier
resourceId	string	Reference to organization-level resource
name	string	Full class name
shortName	string	Abbreviated class name
color	string	Class display color (hex)
classTeacher	string	Teacher ID of the class teacher

Room Object

Field	Type	Description
id	string	Unique room identifier
resourceId	string	Reference to organization-level resource
name	string	Full room name
shortName	string	Abbreviated room name
color	string	Room display color (hex)
capacity	number	Room capacity (number of students)
buildingName	string	Building where room is located
groupName	string	Room group for interchangeable rooms

Lesson Object

Field	Type	Description
id	string	Unique lesson identifier
teacherIds	array	Array of teacher IDs assigned to lesson
classIds	array	Array of class IDs for this lesson
subjectIds	array	Array of subject IDs for this lesson
roomIds	array	Array of room IDs for this lesson
roomGroupName	string	Room group name for flexible room assignment
groups	array	Array of group objects (for split classes)

Lesson Unit Object

Field	Type	Description
id	string	Unique lesson unit identifier
lessonId	string	Reference to parent lesson
day	string	Day of the week (null if unscheduled)
weekIndex	number	Week index for multi-week schedules (null for all weeks)
periodIndex	number	Period slot index, 0-based (null if unscheduled)
length	number	Duration in consecutive periods
classIds	array	Array of class IDs for this unit
subjectIds	array	Array of subject IDs for this unit
teacherIds	array	Array of teacher IDs for this unit
roomIds	array	Array of room IDs for this unit
groups	array	Array of group objects (for split classes)
locked	boolean	Whether this unit's position is locked
lockReason	string	Reason for lock (user_fixed, user_locked, class_teacher)
sectionIds	array	Section IDs (student-level scheduling only)
studentIds	array	Student IDs (student-level scheduling only)

Student-Level Scheduling Fields

When schedulingMode is student-level, the response includes additional fields:

Field	Type	Description
students	array	Array of student objects
courses	array	Array of course objects
sections	array	Array of section objects
sectionSettings	object	Settings for section auto-generation

Error Responses

404 Not Found

Timetable not found or access denied.

{
  "success": false,
  "error": {
    "code": "TIMETABLE_NOT_FOUND",
    "message": "Timetable not found or access denied"
  }
}

401 Unauthorized

Missing or invalid API key.

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or not found"
  }
}

Code Examples

cURL

curl -X GET \
  'https://www.timetablemaster.com/api/v1/timetables/tt_67890' \
  -H 'Authorization: Bearer ttm_your_api_key_here' \
  -H 'Content-Type: application/json'

JavaScript

const timetableId = "tt_67890";

const response = await fetch(
  `https://www.timetablemaster.com/api/v1/timetables/${timetableId}`,
  {
    method: "GET",
    headers: {
      Authorization: "Bearer ttm_your_api_key_here",
      "Content-Type": "application/json",
    },
  }
);

const data = await response.json();

if (data.success) {
  const timetable = data.data;
  console.log(`Timetable: ${timetable.name}`);
  console.log(`Scheduling Mode: ${timetable.schedulingMode}`);
  console.log(`Total lessons: ${timetable.lessons.length}`);
  console.log(`Total lesson units: ${timetable.lessonUnits.length}`);

  // Get scheduled vs unscheduled counts
  const scheduled = timetable.lessonUnits.filter(u => u.day !== null);
  const unscheduled = timetable.lessonUnits.filter(u => u.day === null);
  console.log(`Scheduled: ${scheduled.length}, Unscheduled: ${unscheduled.length}`);
}

Python

import requests

timetable_id = 'tt_67890'
url = f'https://www.timetablemaster.com/api/v1/timetables/{timetable_id}'
headers = {
    'Authorization': 'Bearer ttm_your_api_key_here',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)
data = response.json()

if data['success']:
    timetable = data['data']
    print(f"Timetable: {timetable['name']}")
    print(f"Scheduling Mode: {timetable['schedulingMode']}")
    print(f"Total subjects: {len(timetable['subjects'])}")
    print(f"Total teachers: {len(timetable['teachers'])}")
    print(f"Total classes: {len(timetable['classes'])}")
    print(f"Total lessons: {len(timetable['lessons'])}")
    print(f"Total lesson units: {len(timetable['lessonUnits'])}")

PHP

<?php
$timetableId = 'tt_67890';
$url = "https://www.timetablemaster.com/api/v1/timetables/{$timetableId}";
$headers = [
    'Authorization: Bearer ttm_your_api_key_here',
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if ($data['success']) {
    $timetable = $data['data'];
    echo "Timetable: " . $timetable['name'] . "\n";
    echo "Scheduling Mode: " . $timetable['schedulingMode'] . "\n";
    echo "Lesson units: " . count($timetable['lessonUnits']) . "\n";
}
?>

Use Cases

Display Weekly Timetable

Create a visual timetable grid from the lesson units:

function createTimetableGrid(timetableData) {
  const { bellSchedule, lessonUnits, subjects, teachers, rooms, classes } =
    timetableData;

  // Get days and periods from bell schedule
  const dayConfig = bellSchedule.dayConfigurations[0];
  const dayNames = dayConfig.days;
  const periodsPerDay = dayConfig.periods.length;

  // Create lookup maps for easy reference
  const subjectMap = new Map(subjects.map((s) => [s.id, s]));
  const teacherMap = new Map(teachers.map((t) => [t.id, t]));
  const roomMap = new Map(rooms.map((r) => [r.id, r]));
  const classMap = new Map(classes.map((c) => [c.id, c]));

  // Group lesson units by day and period (only scheduled ones)
  const grid = {};
  dayNames.forEach((day) => {
    grid[day] = new Array(periodsPerDay).fill(null);
  });

  lessonUnits
    .filter(unit => unit.day !== null && unit.periodIndex !== null)
    .forEach((unit) => {
      grid[unit.day][unit.periodIndex] = {
        subject: subjectMap.get(unit.subjectIds[0]),
        teacher: teacherMap.get(unit.teacherIds[0]),
        room: roomMap.get(unit.roomIds[0]),
        class: classMap.get(unit.classIds[0]),
        locked: unit.locked,
      };
    });

  return grid;
}

Extract Teacher Schedules

Get individual teacher schedules from the timetable data:

def extract_teacher_schedule(timetable_data, teacher_id):
    lesson_units = timetable_data['lessonUnits']
    teacher_slots = []

    for unit in lesson_units:
        # Skip unscheduled units
        if unit['day'] is None:
            continue

        if teacher_id in unit['teacherIds']:
            teacher_slots.append({
                'day': unit['day'],
                'period': unit['periodIndex'],
                'weekIndex': unit['weekIndex'],
                'subject': next((s['name'] for s in timetable_data['subjects']
                              if s['id'] in unit['subjectIds']), 'Unknown'),
                'class': next((c['name'] for c in timetable_data['classes']
                             if c['id'] in unit['classIds']), 'Unknown'),
                'room': next((r['name'] for r in timetable_data['rooms']
                             if r['id'] in unit['roomIds']), 'No room assigned'),
                'locked': unit['locked']
            })

    return sorted(teacher_slots, key=lambda x: (x['day'], x['period']))

Room Utilization Analysis

Analyze room usage patterns:

function analyzeRoomUtilization(timetableData) {
  const { lessonUnits, rooms, bellSchedule } = timetableData;

  const dayConfig = bellSchedule.dayConfigurations[0];
  const totalSlots = dayConfig.days.length * dayConfig.periods.length;

  const roomUsage = {};

  rooms.forEach((room) => {
    roomUsage[room.id] = {
      name: room.name,
      building: room.buildingName,
      capacity: room.capacity,
      groupName: room.groupName,
      usedSlots: 0,
      utilization: 0,
    };
  });

  // Only count scheduled lesson units
  lessonUnits
    .filter(unit => unit.day !== null)
    .forEach((unit) => {
      unit.roomIds.forEach((roomId) => {
        if (roomUsage[roomId]) {
          roomUsage[roomId].usedSlots += unit.length || 1;
        }
      });
    });

  Object.values(roomUsage).forEach((room) => {
    room.utilization = (room.usedSlots / totalSlots) * 100;
  });

  return roomUsage;
}

Working with Multi-Week Schedules

Handle cyclic or fixed multi-week schedules:

function getLessonUnitsForWeek(timetableData, weekIndex) {
  const { lessonUnits, bellSchedule } = timetableData;

  // For weekly schedules, return all units
  if (bellSchedule.scheduleType === 'weekly') {
    return lessonUnits.filter(unit => unit.day !== null);
  }

  // For cyclic/fixed schedules, filter by weekIndex
  return lessonUnits.filter(unit => {
    if (unit.day === null) return false;
    // null weekIndex means "all weeks"
    return unit.weekIndex === null || unit.weekIndex === weekIndex;
  });
}

Next Steps

With the complete timetable data, you can:

• Build visual timetable displays for your application
• Extract specific schedules for teachers, classes, or rooms
• Analyze timetable patterns and utilization
• Integrate the data with your school management system
• Handle multi-week cyclic schedules
• Work with locked/fixed lesson positions