ClassCharts API (JavaScript/TypeScript)
ClassCharts is a UK education classroom management platform. This skill uses the unofficial classcharts-api JS library to fetch homework, behaviour, timetable, detentions, attendance, announcements, badges, and more. Supports both Parent and Student authentication.
Important: The API is unofficial. Never hardcode credentials in prompts, logs, or committed code. Use environment variables or a secure secret store.
Installation
npm install classcharts-api
Requirements: Node.js 20+ or Deno
Authentication
Two client types with different login flows:
Parent Client
Parent logs in with email and password. Access to all linked pupils.
import { ParentClient } from "classcharts-api";
const client = new ParentClient(
process.env.CLASSCHARTS_EMAIL!,
process.env.CLASSCHARTS_PASSWORD!,
);
await client.login();
// Defaults to first pupil; switch with selectPupil
const pupils = client.pupils; // or await client.getPupils()
client.selectPupil(pupils[1].id); // if multiple children
Student Client
Student logs in with ClassCharts code and date of birth.
import { StudentClient } from "classcharts-api";
// Date of birth MUST be DD/MM/YYYY
const client = new StudentClient(
process.env.CLASSCHARTS_CODE!, // e.g. "ABCD1234"
"01/01/2010",
);
await client.login();
Date formats
| Use case | Format | Example |
|---|---|---|
| API options (from, to, date) | YYYY-MM-DD | "2024-03-10" |
| Student date of birth (login) | DD/MM/YYYY | "01/01/2010" |
| getStudentCode dateOfBirth | YYYY-MM-DD | "2010-01-01" |
Shared methods (Parent & Student)
All methods require await client.login() first. Session auto-renews after 3 minutes.
| Method | Options | Description |
|---|---|---|
getStudentInfo() | — | Student profile and metadata |
getActivity({ from, to, last_id? }) | Dates YYYY-MM-DD, optional pagination | Activity feed (paginated) |
getFullActivity({ from, to }) | Dates YYYY-MM-DD | Activity between dates (auto-paginates) |
getBehaviour({ from?, to? }) | Dates YYYY-MM-DD | Behaviour points timeline and reasons |
getHomeworks({ from?, to?, displayDate? }) | Dates, displayDate: "due_date" | "issue_date" | Homework list |
getLessons({ date }) | date: YYYY-MM-DD | Timetable for a specific date |
getBadges() | — | Earned badges |
getAnnouncements() | — | School announcements |
getDetentions() | — | Detentions |
getAttendance({ from, to }) | Dates YYYY-MM-DD | Attendance records |
getPupilFields() | — | Custom pupil fields/stats |
Parent-only methods
| Method | Description |
|---|---|
getPupils() | List pupils linked to parent account |
selectPupil(pupilId) | Set active pupil for subsequent requests |
changePassword(current, new) | Change parent account password |
Student-only methods
| Method | Description |
|---|---|
getRewards() | Rewards shop items and balance |
purchaseReward(itemId) | Purchase item from rewards shop |
getStudentCode({ dateOfBirth }) | Get student code (dateOfBirth: YYYY-MM-DD) |
Quick examples
// Homework for date range
const homeworks = await client.getHomeworks({
from: "2024-03-01",
to: "2024-03-31",
displayDate: "due_date",
});
// Today's timetable
const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
const lessons = await client.getLessons({ date: today });
// Behaviour summary
const behaviour = await client.getBehaviour({
from: "2024-01-01",
to: "2024-03-10",
});
// Student: list rewards shop and purchase
const rewards = await client.getRewards();
const purchase = await client.purchaseReward(rewards.data[0].id);
Response shape
Responses follow ClassChartsResponse<Data, Meta>:
{
success: 1,
data: T, // Array or object depending on endpoint
meta: M, // Session ID, dates, counts, etc.
error?: string
}
Errors throw if success === 0.
When to use this skill
- User asks about ClassCharts, school homework, behaviour points, timetable, detentions, attendance, or rewards.
- User wants to script, integrate, or automate ClassCharts data.
- User mentions parent/student portal in the context of UK schools and ClassCharts.