This is an unofficial Node.js implementation of the Edupage API. This module is not maintained, authorized, or sponsored by Edupage. Edupage's internal API could change at any time, and break functionality of this module. If you find bugs, have any questions or suggestions for features, please let me know and submit an issue.
EdupageAPI is a module to easily access and interact with your Edupage account. All the basic types like students, teachers, subjects, timetables, messages are stored into the groups with user-friendly API to get data and do basic actions (obtaining lessons, replying to messages...). You can also a send message marked as Important, which is not possible using the official Edupage application (unless you have an account with teacher privileges).
- Node.js v14.0.0+
- Edupage account
npm i edupage-apiThe only thing you need to set up the API is to log in, like so:
const {Edupage} = require("edupage-api");
// Create blank Edupage instance
const edupage = new Edupage();
// This will automatically create new User instance and
// fill in all arrays and properties inside `edupage`
edupage.login("username/email", "password").then(user => {
// Currently logged user (`user`) can be also accessed by `edupage.user`
// Here you can write your code...
}).catch(err => {
// Catch errors
});Most of the objects have _data property, which holds raw data fetched directly from Edupage servers so in case there are no parsed properties you are looking for, you can get raw data by accessing those _data properties and process it yourself.
Note: In production, you should be handling Promise rejections by promise.catch() or try ... catch.
This example shows how to obtain timetable (with lessons) for current date. Initially there are available 2 to 4 timetables only, but this method tries to automatically fetch and update given timetables.
const {Edupage} = require("edupage-api");
const edupage = new Edupage();
(async () => {
await edupage.login("username", "password");
//Get today's date for example
const date = new Date();
//Get timetable for `date`
const timetable = await edupage.getTimetableForDate(date);
//Get array with lessons for this timetable
const lessons = timetable.lessons;
console.log(lessons);
edupage.exit(); //To exit the process
})();This simple snippet returns each homework and test happening the next day (from today) as an array of the assignments.
const {Edupage} = require("edupage-api");
const edupage = new Edupage();
(async () => {
await edupage.login("username", "password");
//Get tomorrow's date
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
//Get lessons
const timetable = await edupage.getTimetableForDate(tomorrow);
const lessons = timetable.lessons;
//Collect assignments
const homeworks = lessons.reduce((arr, lesson) => (arr.push(...lesson.assignments), arr), []);
console.log(homeworks);
edupage.exit(); //To exit the process
})();If you need to access multiple timetables at once, you can use this method.
Note: You shouldn't be calling this method in loop for same date range, use getTimetableForDate method instead which reads from cache.
const {Edupage} = require("edupage-api");
const edupage = new Edupage();
(async () => {
await edupage.login("username", "password");
//Choose a date range
const from = new Date("2021-05-10");
const to = new Date("2021-05-15");
//Fetch array of the timetables
//Note: This will also update `edupage.timetables` array
const timetables = await edupage.fetchTimetablesForDates(from, to);
console.log(timetables);
edupage.exit(); //To exit the process
})();Using this simple snippet you can tell your teacher that you are present on the lesson.
const {Edupage} = require("edupage-api");
const edupage = new Edupage();
(async () => {
await edupage.login("username", "password");
//Get today's date for example
const date = new Date();
//Get timetable for today
const timetable = await edupage.getTimetableForDate(date);
//Get your lesson
//Note: This will return second lesson in array, not second period.
// In case you want to access second period you may need:
// `timetable.lessons.find(e => e.period.id == "3")`
const lesson = timetable.lessons[1];
//You should check if the lesson is an online lesson
if(lesson.isOnlineLesson) {
//Sign it (this method may not be successful, in such case it will return `false`)
const success = await lesson.signIntoLesson();
console.log(success);
}
edupage.exit(); //To exit the process
})();This example shows how to send a simple message to another user.
const {Edupage} = require("edupage-api");
const edupage = new Edupage();
(async () => {
await edupage.login("username", "password");
//Get the user
const classmate = edupage.students.find(e => e.firstname == "John" && e.lastname == "Smith");
//Configure the message
const options = {
text: "Hello there!", //Message content
important: true //Make this message marked as important
};
//Send the message
await classmate.sendMessage(options);
edupage.exit(); //To exit the process
})();This example shows how to send a message with an attachment(s) to another user.
const {Edupage} = require("edupage-api");
const edupage = new Edupage();
(async () => {
await edupage.login("username", "password");
//Get a user
const teacher = edupage.teachers.find(e => e.firstname == "John" && e.lastname == "Smith");
//Upload the attachment
const attachment = await edupage.uploadAttachment("C:/Users/username/Documents/Homework.docx");
//Configure the message
const options = {
text: "Sending my homework!", //Message content
attachments: [attachment] //Array of attachments
};
//Send the message
await teacher.sendMessage(options);
edupage.exit(); //To exit the process
})();Using this snippet you can access material data and/or results of an assignment. This method is not implemented yet, so you have to process it yourself.
const {Edupage} = require("edupage-api");
const edupage = new Edupage();
(async () => {
await edupage.login("username", "password");
//Get an assignment (you can search by title, id...)
const assignment = edupage.assignments.find(e => e.title.startsWith("Surface integral of vector field"));
//Get the data
//Note: This returns RawDataObject (it might get implemented in the future)
const {materialData, resultsData} = await assignment.getData();
console.log(materialData, resultsData);
edupage.exit(); //To exit the process
})();🚨 This example is experimental, you should avoid using it in production until stable version!
Are you annoyed sending each week a new infectivity application? You can make that programmatically now! The following snipped shows how to post Covid-19 infectivity application with current date.
const {Edupage} = require("edupage-api");
const edupage = new Edupage();
(async () => {
await edupage.login("username", "password");
//Get an application you want to post
const application = edupage.applications.find(e => e.id == "teacher_infectivity_2_20210517");
//Get today's date
const today = new Date();
//Post the application
const success = await application.post({
date: Edupage.dateToString(today) //Processing for the values is not supported, so you have to make it yourself
});
//Console.log the result (🚨 This might not be precise!)
console.log(success);
edupage.exit(); //To exit the process
})();Here you can find representations of all classes, interfaces and enums. In code, you shouldn't be creating any instances of the following classes except for Edupage class. All required classes are created internally. Most of the classes contain Edupage instance.
Note: following snippets are not actual valid code.
- Classes
- class ASC
- class Application
- class Assignment
- class Attachment
- class Class
- class Classroom
- class Edupage
- class Grade
- class Homework
- class Lesson
- class Message
- class Parent
- class Period
- class Plan
- class RawData
- class Season
- class Student
- class Subject
- class Teacher
- class Test
- class Timetable
- class User
- Interfaces
- Enums
This class holds the basic information about a school and logged user.
class ASC extends RawData {
edupage: Edupage;
loggedUser: string; // UserString of the currently logger user
loggedUserRights: any[];
lang: string; // Language code
timezone: string; // Example: "Europe/Bratislava"
firstDayOfWeek: number; // 0 = sunday
weekendDays: number[]; // 0 = sunday
schoolName: string; // Long name of the school
schoolCountry: string; // Country code
schoolyearTurnover: string; // Example: "08-01"
server: string;
gsecHash: string;
gpids: string[];
gpid?: string;
}🚨 This is an experimental class, you should not be using this class in production
This class holds the information about an application (e.g. Covid-19 infectivity)
class Application extends RawData {
edupage: Edupage;
id: string;
name: string;
dateFrom: Date;
dateTo: Date;
parameters: string[]; // List of parameters to be passed to `Application.post(...)`
availableFor: EntityType; // Usually `ENTITY_TYPE.STUDENT` or `ENTITY_TYPE.TEACHER`
isEnabled: boolean; // Determines whether the application is enabled in your Edupage
isTextOptional: boolean; // Unknown property
isAdvancedWorkflow: boolean; // Unknown property
isSimpleWorkflow: boolean; // Unknown property
// Creates draft for the application
async createDraft(): Promise<string>;
// Posts the application
// 🚨 This method might not return accurate result
static post(
parameters: RawDataObject = {}, // Parameters from `Application.parameters`
draftId?: string = null // Draft ID (created internally if not provided)
): Promise<boolean>;
}This class holds the information about an assignment such as homework, test, presentation...
class Assignment extends RawData {
edupage: Edupage;
id: string;
superId: string;
testId: string;
hwkid: string;
type: AssignmentType;
owner: User | Teacher; // Creator of the assignment
subject: Subject;
period: Period;
grades: Grade[];
creationDate: Date; // Time when was the assignment created
fromDate: Date; // Time from when is the assignment available for students
toDate: Date; // Time until the assignment is available for students
duration: number; // Number of seconds for students to submit the assignment
title: string;
details: string;
comment: string;
result: string;
state: string;
stateUpdatedDate: Date;
stateUpdatedBy: User | Teacher;
cardsCount: number;
answerCardsCount: number;
isSeen: boolean;
isFinished: boolean;
async getData(): Promise<RawDataObject>;
static from(
data: RawDataObject,
edupage: Edupage
): Assignment | Homework | Test;
}This class holds the information about an attachment.
class Attachment extends RawData {
edupage: Edupage;
name: string; // Name containing file extension
src: string; // Source url, absolute path
}This class holds basic the information about a school class.
class Class extends RawData {
edupage: Edupage;
id: string;
grade: number; // e.g. first grade, second grade etc.
name: string;
short: string;
classroom: Classroom;
teacher?: Teacher;
teacher2?: Teacher;
}This class holds basic the information about a classroom.
class Classroom extends RawData {
edupage: Edupage;
id: string;
name: string;
short: string;
cb_hidden: boolean;
}This is the main EdupageAPI class, containing all resources fetched and parsed from the Edupage servers.
You can access all properties and methods to obtain required data.
The property _data contains original raw data. (As well as some data which are not supported yet)
class Edupage extends RawData {
user: User | Teacher | Student; // Gets assigned automatically after successful login() call
students: Student[];
teachers: Teacher[];
parents: Parent[];
plans: Plan[];
classes: Class[];
classrooms: Classroom[];
seasons: Season[];
periods: Period[];
subjects: Subject[];
timetables: Timetable[];
timelineItems: Message[]; // Contains all timeline items (including confirmations)
timeline: Message[]; // Contains only visible items (messages, assignments, grades...)
assignments: Assignment[]; // Contains all assignments (homework assignments, tests and other)
homeworks: Homework[]; // Contains assignments type of homework
tests: Test[]; // Contains assignments type of test
ASC: ASC;
year: number;
baseUrl: string; // Example: "https://example.edupage.org"
getUserById(id: string): User | Teacher | Student | Parent | undefined;
getUserByUserString(userString: string): User | Teacher | Student | Parent | undefined;
getYearStart(time?: boolean = false): string; // Example: "2020-08-01" or "2020-08-01 00:00:00"
async getTimetableForDate(date: Date): Promise<Timetable | undefined>; // Note: Calls `fetchTimetablesForDates` method internally if the given timetable is missing
async fetchTimetablesForDates( // Fetches the timetables from Edupage (+caching and updating existing)
fromDate: Date,
toDate: Date
): Promise<Timetable[]>
async login(
username: string,
password: string
): Promise<User | Teacher | Student>;
async refresh(): void; // Refreshes all values in current instance
async refreshEdupage(_update?: boolean = true): void; // Refreshes global Edupage data (such as teachers, classes, classrooms, subjects...)
async refreshTimeline(_update?: boolean = true): void; // Refreshes timeline data (messages, notifications...)
async refreshCreatedItems(_update?: boolean = true): void; // Refreshes timeline items data created by currently logged user
async refreshGrades(_update?: boolean = true): void; // Refreshes grades of currently logged user
_updateInternalValues(): void; // Updates all fields of the current instance (called internally after
// any of the "refresh" methods, if `_update` is set to `true`)
async uploadAttachment(filepath: string): Promise<Attachment>;
async api(options: APIOptions, _count: number = 0): Promise<RawDataObject | string, Error | {retry: true, count: number}>;
scheduleSessionPing(): void;
async pingSession(): Promise<boolean>;
exit(): void; // Stops internal timers to prevent process from hanging infinitely.
static compareDay(
date1: Date | number | string,
date2: Date | number | string
): boolean;
static dateToString( // Converts Date into string (Example: "2020-05-17")
date: Date
): string;
}This class holds the information about a student's grade.
Note: properties points, maxPoints and percentage are only available if type == "3".
class Grade extends RawData {
edupage: Edupage;
id: string;
eventId: string;
superId: string;
type: string;
state: string;
provider: string; // Usually "edupage"
student: Student;
teacher: Teacher;
creationDate: Date;
signedDate: Date;
signedByParentDate: Date;
plan: Plan;
class: Class;
classes: Class[];
season: Season;
subject: Subject;
assignment: Assignment;
title: string;
short: string;
date: string;
value: string; // Actual grade
weight: number; // Weight of the grade as decimal number (Example: 0.25)
points?: number; // Points gained
maxPoints?: number; // Max possible points
percentage?: number; // Ratio between gained points and maxPoints in percents
average: string; // Average gained points / grade in class
isSigned: boolean;
isClassified: boolean;
}This is a wrapper class for the Assignment class
class Homework extends Assignment {
}This class holds the information about a lesson.
class Lesson extends RawData {
edupage: Edupage;
id: string;
lid: string;
students: Student[];
teachers: Teacher[];
classes: Class[];
classrooms: Classroom[];
date: Date; // Starting time of the lesson
period: Period;
subject: Subject;
assignments: Assignment[];
onlineLessonURL: string;
homeworkNote: string;
absentNote: string;
curriculum: string;
isOnlineLesson: boolean;
async signIntoLesson(): Promise<boolean>;
}This class holds the information about a message. You can also do some basic actions like replying, liking the message, starring the message...
class Message extends RawData {
edupage: Edupage;
id: string;
otherId: string;
type: TimelineItemType;
owner: User | Teacher | Student | Parent; // Sender or Author
recipient: User | Teacher | Student | Parent | Plan | Class;
recipientUserString: string; // In some cases, the recipient cannot be parsed, so this property holds it's raw UserString
participants: (User | Teacher | Student | Parent)[];
participantsCount: number;
creationDate: Date; // Time when the message was created
timelineDate: Date; // Time on the timeline (when someone reacts to the message, it will get pushed at the top of the timeline)
lastReplyDate: Date; // Time of the last reply
seenDate: Date; // Time when the message has been seen (this will be always same as `creationDate` if the message is not important)
likedDate: Date;
doneDate: Date;
likedBy: ({
user: User | Teacher | Student | Parent,
date: Date
})[];
seenBy: ({
user: User | Teacher | Student | Parent,
date: Date
})[];
text: string;
title: string;
likes: number;
replyOf: Message;
replies: Message[];
repliesCount: number;
attachments: Attachment[];
assignment: Assignment;
isRemoved: boolean;
isReply: boolean;
isImportant: boolean;
isSeen: boolean; // This will be always true if the message is not important
isLiked: boolean;
isDone: boolean;
isStarred: boolean;
isWildcardRecipient: boolean; // Determines whether exact recipient is known (you should be using `recipientUserString` if this is true)
async markAsSeen(): Promise<void>;
async markAsLiked(state?: boolean = true): Promise<boolean>;
async markAsDone(state?: boolean = true): Promise<boolean>;
async markAsStarred(state?: boolean = true): Promise<boolean>;
async reply(options: MessageReplyOptions): void;
async refresh(data?: RawDataObject = null): void; // To refresh message content (e.g. replies) call this method (ignoring `data` paramenter)
}This class holds the basic information about a parent.
class Parent extends User {
edupage: Edupage;
id: string;
userString: string;
firstname: string;
lastname: string;
gender: GENDER;
}This class holds the information about a school period.
class Period extends RawData {
id: string; // Starts from 1
name: string;
short: string;
startTime: string;
endTime: string;
getInvalid(data?: { //Creates new invalid Period
id?: string?,
name?: string,
short?: string,
startTime?: string,
endTime?: string
} = null): Period;
}This class holds the information about a school Plan. It's like a group of specific students for some subject.
class Plan extends RawData {
edupage: Edupage;
id: string;
otherId: string;
customClassId: string;
teacher: Teacher;
teachers: Teacher[];
students: Student[];
changedDate: Date;
approvedDate: Date;
name: string;
customName: string;
classOrdering: number;
year: number;
season: Season;
subject: Subject;
classes: Class[];
state: string;
timetableGroup: string;
settings: Object<string, any>;
topicsCount: number;
taughtCount: number;
standardsCount: number;
isEntireClass: boolean;
isApproved: boolean;
isPublic: boolean;
isValid: boolean;
}This is the base class for storing raw data fetched from Edupage servers.
It contains a single property - _data, this property is non-enumerable
class RawData {
_data: RawDataObject;
}This class holds the information about a school season. It could be month, semester...
class Season extends RawData {
edupage: Edupage;
id: string;
index: number; // Starting from 1 (e.g. first month of the school year)
types: string[]; // ? Unknown property
fromDate: Date;
toDate: Date;
name: string;
halfYear: number; // First or second semester
supSeason: Season; // Upper season (e.g. if `this` is the first month, this property will be first a half year)
classificationSeason?: Season;
isClassification: boolean;
}This class holds the information about a student.
class Student extends User {
edupage: Edupage;
class: Class;
number: number; // ? Unknown property
numberInClass: number; // This is actual number in class
parent1Id: string;
parent2Id: string;
parent3Id: string;
parent1?: Parent;
parent2?: Parent;
parent3?: Parent;
userString: string;
getUserString(parents?: boolean = false): string;
}This class holds the information about a subject.
class Subject extends RawData {
id: string;
name: string;
short: string;
}This class holds the information about a teacher.
class Teacher extends User {
edupage: Edupage;
classroom: Classroom;
short: string;
userString: string;
cb_hidden: number; // ? Unknown property
}This is a wrapper class for the Assignment class.
class Test extends Assignment {
}This class holds the information about a timetable. Timetable for only single day, not entire week.
class Timetable extends RawData {
edupage: Edupage;
date: Date;
week: number; // ? Unknown property (Maybe odd/even week?)
lessons: Lesson[];
}This class holds the information about a user.
Use sendMessage method to send message to the user.
class User extends RawData {
edupage: Edupage;
id: string;
origin: string;
userString: string;
dateFrom: Date;
dateTo: Date;
firstname: string;
lastname: string;
gender: Gender;
email?: string;
cookies?: CookieJar;
credentials?: {
username: string,
password: string
};
isLoggedIn: boolean;
isOut: boolean;
getUserString(): string;
async sendMessage(options: MessageOptions): Message;
async login(
username: string,
password: string
): Promise<User>;
static from(
userString: string,
data?: RawDataObject = {},
edupage?: Edupage = null
): User | Teacher | Student | Parent;
}Using this interface you can specify the API options.
interface APIOptions {
url: string | APIEndpoint; // APIEndpoint is automatically resolved
data?: (Object<string, any> | stream.Readable | Buffer | string) = {};
headers?: Object<string, any> = {};
method?: string = "POST";
encodeBody?: boolean = true; // Encode body as `form-urlencoded` using Edupage "special" encryption
type?: "json" | "text" = "json"; // Response type
autoLogin?: boolean = true; // Log in the user automatically if they're logged out (e.g. expired session)
}Using this interface you can specify the message options.
interface MessageOptions {
text: string; // Content of the message
important?: boolean = false; // Mark message as important
parents?: boolean = false; // Include parents
attachments?: Attachment[] = [];
}Using this interface you can specify the message options for reply.
interface MessageReplyOptions {
text: string; // Content of the reply
recipient?: (User | Teacher | Student | Parent) = null; // Send only to the exact user
parents?: boolean = false; // Include parents
attachments?: Attachment[] = []
}This interface is used to represent raw data fetched from the Edupage servers.
interface RawDataObject {
[property: string]: any;
}This enum contains records about the API endpoints.
enum APIEndpoint {
DASHBOARD_GET_USER,
DASHBOARD_SIGN_ONLINE_LESSON,
TIMELINE_GET_DATA,
TIMELINE_GET_REPLIES,
TIMELINE_GET_CREATED_ITEMS,
TIMELINE_CREATE_ITEM,
TIMELINE_CREATE_CONFIRMATION,
TIMELINE_CREATE_REPLY,
TIMELINE_FLAG_HOMEWORK,
TIMELINE_UPLOAD_ATTACHMENT,
ELEARNING_TEST_DATA,
ELEARNING_TEST_RESULTS,
ELEARNING_CARDS_DATA,
GRADES_DATA
}This enum contains records about the API response statuses.
enum APIStatus {
OK = "ok",
FAIL = "fail"
}This enum contains records about the assignment types.
enum AssignmentType {
HOMEWORK = "hw",
ETEST_HOMEWORK = "etesthw",
BIG_EXAM = "bexam",
EXAM = "exam",
SMALL_EXAM = "sexam",
ORAL_EXAM = "oexam",
REPORT_EXAM = "rexam",
TESTING = "testing",
TEST = "test",
PROJECT_EXAM = "pexam",
ETEST = "etest",
ETEST_PRINT = "etestprint",
ETEST_LESSON = "etestlesson",
LESSON = "lekcia",
PROJECT = "projekt",
RESULT = "result",
CURRICULUM = "ucivo",
TIMELINE = "timeline"
}This enum contains records about the assignments groups.
enum AssignmentGroup {
HOMEWORK = ["hw", "etesthw"],
EXAM = ["bexam", "sexam", "oexam", "rexam", "testing"],
TEST = ["test", "etest", "etestprint"],
PROJECT = ["pexam", "projekt"],
PRESENTATION = ["etestlesson", "lekcia"],
OTHER = ["result", "ucivo", "timeline"]
}This enum contains records about the entity types.
enum EntityType {
STUD_PLAN = "StudPlan",
STUDENT = "Student",
CUST_PLAN = "CustPlan",
STUDENT_ONLY = "StudentOnly",
STUD_CLASS = "StudTrieda",
TEACHER = "Ucitel",
ALL = "*",
CLASS = "Trieda",
STUDENT_ALL = "Student*",
STUDENTONLY_ALL = "StudentOnly*",
TEACHER_ALL = "Ucitel*",
ADMIN = "Admin",
PARENT = "Parent"
}This enum contains records about the genders.
enum Gender {
MALE = "M",
FEMALE = "F"
}This enum contains records about the timeline item types.
enum TimelineItemType {
MESSAGE = "sprava",
MESSAGE_TO_SUBTITUTER = "spravasuplujucemu",
NOTICEBOARD = "nastenka",
GRADE_ANNOUNCEMENT = "nastenka",
GRADE = "znamka",
NOTE = "vcelicka",
HOMEWORK = "homework",
HOMEWORK_STUDENT_STATE = "homework",
ABSENCE_NOTE = "ospravedlnenka",
ABSENCE_NOTE_REMINDER = "ospravedlnenka_reminder",
PROCESS = "process",
PROCESS_ADMIN = "processadmin",
STUDENT_ABSENT = "student_absent",
ACCIDENT = "accident",
EVENT = "event",
TIMETABLE = "timetable",
SUBSTITUTION = "substitution",
CANTEEN_MENU = "stravamenu",
CANTEEN_CREDIT = "strava_kredit",
CANTEEN_SUSPEND_REINSTATE_ORDERS = "strava_prerusObnovObj",
CANTEEN_OPENING = "strava_vydaj",
SURVEY = "anketa",
PLAN = "plan",
SETTINGS = "settings",
ALBUM = "album",
NEWS = "news",
TEST_ASSIGNMENT = "testpridelenie",
TEST_RESULT = "testvysledok",
CHAT = "chat",
CHECK_IN = "pipnutie",
CONSULTATION_MESSAGE = "konzultaciemsg",
CONSULTATION = "konzultacie",
PAYMENTS = "payments",
SIGN_IN = "signin",
CURRICULUM = "ucivo",
CURRICULUM_REMINDER = "ucivo_reminder",
BLACKBOARD = "bb",
STUDENT_PICKUP = "odchadzka",
TIMETABLE_CLOUD_GENERATE = "ttcloudgen",
CONFIRMATION = "confirmation",
CONTEST = "contest"
}
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent