Get Timetable Data

Retrieve complete timetable data for a specific timetable by ID. This endpoint returns all timetable information including subjects, teachers, classes, rooms, and 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",
    "generalSettings": {
      "timetableName": "Term 1 2025 Timetable",
      "periodsPerDay": 8,
      "periods": [
        {
          "start_time": "08:00",
          "end_time": "08:45"
        },
        {
          "start_time": "08:45",
          "end_time": "09:30"
        }
      ],
      "breaks": [
        {
          "start_time": "10:15",
          "end_time": "10:30"
        },
        {
          "start_time": "12:30",
          "end_time": "13:15"
        }
      ],
      "daysPerWeek": 5,
      "dayNames": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
    },
    "subjects": [
      {
        "id": "math_001",
        "name": "Mathematics",
        "shortName": "Math",
        "color": "#FF5733"
      },
      {
        "id": "eng_001",
        "name": "English",
        "shortName": "Eng",
        "color": "#33FF57"
      }
    ],
    "teachers": [
      {
        "id": "teacher_001",
        "name": "John Smith",
        "shortName": "J.Smith",
        "color": "#3357FF"
      },
      {
        "id": "teacher_002",
        "name": "Sarah Johnson",
        "shortName": "S.Johnson",
        "color": "#FF33F5"
      }
    ],
    "classes": [
      {
        "id": "class_9a",
        "name": "Grade 9A",
        "shortName": "9A",
        "color": "#F5FF33",
        "classTeacher": "teacher_001"
      },
      {
        "id": "class_9b",
        "name": "Grade 9B",
        "shortName": "9B",
        "color": "#33FFF5",
        "classTeacher": "teacher_002"
      }
    ],
    "rooms": [
      {
        "id": "room_101",
        "name": "Mathematics Room 1",
        "shortName": "M101",
        "color": "#FF5733",
        "buildingName": "Main Building"
      },
      {
        "id": "room_102",
        "name": "English Room 1",
        "shortName": "E101",
        "color": "#33FF57",
        "buildingName": "Language Block"
      }
    ],
    "schedule": [
      {
        "id": "slot_001",
        "day": "Monday",
        "period_index": 0,
        "length": 1,
        "classIds": ["class_9a"],
        "subjectIds": ["math_001"],
        "teacherIds": ["teacher_001"],
        "roomIds": ["room_101"],
        "groups": []
      },
      {
        "id": "slot_002",
        "day": "Monday",
        "period_index": 1,
        "length": 1,
        "classIds": ["class_9b"],
        "subjectIds": ["eng_001"],
        "teacherIds": ["teacher_002"],
        "roomIds": ["room_102"],
        "groups": []
      }
    ],
    "unscheduled": [
      {
        "id": "slot_unsch_001",
        "day": null,
        "period_index": null,
        "length": 1,
        "classIds": ["class_9a"],
        "subjectIds": ["art_001"],
        "teacherIds": ["teacher_003"],
        "roomIds": [],
        "groups": []
      }
    ],
    "status": "published",
    "createdAt": "2025-01-15T08:00:00.000Z",
    "updatedAt": "2025-01-20T14:30:00.000Z"
  },
  "timestamp": "2024-07-15T10:30:00.000Z"
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`data.id`	string	Unique timetable identifier
`data.name`	string	Human-readable timetable name
`data.orgId`	string	Organization identifier
`data.generalSettings`	object	Timetable configuration settings
`data.generalSettings.periodsPerDay`	number	Number of periods per day
`data.generalSettings.periods`	array	Array of period time slots
`data.generalSettings.breaks`	array	Array of break time slots
`data.generalSettings.daysPerWeek`	number	Number of school days per week
`data.generalSettings.dayNames`	array	Names of school days
`data.subjects`	array	Array of subject objects
`data.subjects[].id`	string	Unique subject identifier
`data.subjects[].name`	string	Full subject name
`data.subjects[].shortName`	string	Abbreviated subject name
`data.subjects[].color`	string	Subject display color (hex)
`data.teachers`	array	Array of teacher objects
`data.teachers[].id`	string	Unique teacher identifier
`data.teachers[].name`	string	Full teacher name
`data.teachers[].shortName`	string	Abbreviated teacher name
`data.teachers[].color`	string	Teacher display color (hex)
`data.classes`	array	Array of class objects
`data.classes[].id`	string	Unique class identifier
`data.classes[].name`	string	Full class name
`data.classes[].shortName`	string	Abbreviated class name
`data.classes[].color`	string	Class display color (hex)
`data.classes[].classTeacher`	string	ID of the class teacher
`data.rooms`	array	Array of room objects
`data.rooms[].id`	string	Unique room identifier
`data.rooms[].name`	string	Full room name
`data.rooms[].shortName`	string	Abbreviated room name
`data.rooms[].color`	string	Room display color (hex)
`data.rooms[].buildingName`	string	Building where room is located
`data.schedule`	array	Array of scheduled time slots
`data.schedule[].id`	string	Unique slot identifier
`data.schedule[].day`	string	Day of the week
`data.schedule[].period_index`	number	Period number (0-based)
`data.schedule[].length`	number	Duration in periods
`data.schedule[].classIds`	array	Array of class IDs for this slot
`data.schedule[].subjectIds`	array	Array of subject IDs for this slot
`data.schedule[].teacherIds`	array	Array of teacher IDs for this slot
`data.schedule[].roomIds`	array	Array of room IDs for this slot
`data.schedule[].groups`	array	Array of group objects (for split classes)
`data.unscheduled`	array	Array of unscheduled time slots
`data.status`	string	Timetable status (`draft` or `published`)
`data.createdAt`	string	ISO timestamp when timetable was created
`data.updatedAt`	string	ISO timestamp when timetable was last updated
`timestamp`	string	ISO timestamp of the API response

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(`Periods per day: ${timetable.generalSettings.periodsPerDay}`);
  console.log(`Total scheduled slots: ${timetable.schedule.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"Total subjects: {len(timetable['subjects'])}")
    print(f"Total teachers: {len(timetable['teachers'])}")
    print(f"Total classes: {len(timetable['classes'])}")

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 "Scheduled slots: " . count($timetable['schedule']) . "\n";
    echo "Unscheduled slots: " . count($timetable['unscheduled']) . "\n";
}
?>

Use Cases

Display Weekly Timetable

Create a visual timetable grid from the schedule data:

function createTimetableGrid(timetableData) {
  const { generalSettings, schedule, subjects, teachers, rooms, classes } =
    timetableData;
  const { dayNames, periodsPerDay } = generalSettings;

  // 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 schedule by day and period
  const grid = {};
  dayNames.forEach((day) => {
    grid[day] = new Array(periodsPerDay).fill(null);
  });

  schedule.forEach((slot) => {
    if (slot.day && slot.period_index !== null) {
      grid[slot.day][slot.period_index] = {
        subject: subjectMap.get(slot.subjectIds[0]),
        teacher: teacherMap.get(slot.teacherIds[0]),
        room: roomMap.get(slot.roomIds[0]),
        class: classMap.get(slot.classIds[0]),
      };
    }
  });

  return grid;
}

Extract Teacher Schedules

Get individual teacher schedules from the timetable data:

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

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

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

Room Utilization Analysis

Analyze room usage patterns:

function analyzeRoomUtilization(timetableData) {
  const { schedule, rooms, generalSettings } = timetableData;
  const totalSlots =
    generalSettings.daysPerWeek * generalSettings.periodsPerDay;

  const roomUsage = {};

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

  schedule.forEach((slot) => {
    slot.roomIds.forEach((roomId) => {
      if (roomUsage[roomId]) {
        roomUsage[roomId].usedSlots += slot.length || 1;
      }
    });
  });

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

  return roomUsage;
}

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

Endpoint​

Authentication​

Request​

Path Parameters​

Headers​

Response​

Success Response​

Response Fields​

Error Responses​

404 Not Found​

401 Unauthorized​

Code Examples​

cURL​

JavaScript​

Python​

PHP​

Use Cases​

Display Weekly Timetable​

Extract Teacher Schedules​

Room Utilization Analysis​

Next Steps​