Edulink-API

An Unofficial API for OvernetData's Edulink.

This API provides abstractions over the undocumented Edulink API. It is not official and could be subject to breaking changes.

The Edulink_API class is the main API class, it provides heavy abstractions over the raw data returned by Edulink. The Edulink_Raw class houses the raw requests to the edulink API.

Contents

• Examples

  • Importing the module
  • Initializing and authenticating
  • Getting the latest homework
  • Getting tomorrow's lessons

• Full Documentation

  • Edulink_API class
  • Edulink_Raw class
  • Edulink_Raw_Response_Types

Installation

$ npm install edulink-api

Usage Examples

Importing the module:

import Edulink_API from 'edulink-api';

Creating the API object and authenticating:

You need to login to Edulink first before using the API methods. This is done like this:

const edulink_api = new Edulink_API();

await edulink_api.Authenticate({
  school_code: 'your_school_name',
  username: 'your_username',
  password: 'your_password',
});

Now we can use the API methods on the Edulink_API instance (edulink_api).

Getting the latest homework:

Here we:

• query for all homework.
• select only the currently active homeworks.
• sort the homeworks by due-date and find the one due soonest.
• print some of the homework's data.

import Edulink_API from 'edulink-api';

const edulink_api = new Edulink_API();

await edulink_api.Authenticate({
  school_code: 'your_school_name',
  username: 'your_username',
  password: 'your_password',
});

const homework = await edulink_api.Homework();
const latest_homework = homework.sort(
  (a, b) => new Date(a.due_date) - new Date(b.due_date)
)[0];

console.log(latest_homework);
/*
{
  title: 'Finish Graph and Questions',
  due_date: '2022-01-19',
  subject: 'Chemistry',
  description: "Complete and hand in the questions on page 60",
  completed: false,
  status: 'Not submitted',
  set_by: 'teacher_name',
  due_text: 'Due in 3 days',
  available_date: '2022-01-16 00:00:00',
}
*/

Getting tomorrow's lessons:

import Edulink_API from 'edulink-api';

const edulink_api = new Edulink_API();

await edulink_api.authenticate({
  school_code: 'your_school_name',
  username: 'your_username',
  password: 'your_password',
});

// Getting tommorow's date in the format YYYY-MM-DD
const tomorrow = new Date(new Date().getTime() + 24 * 60 * 60 * 1000)
  .toISOString()
  .split('T')[0];

// Get the lessons from tomorrow
// after we get the response we get the 0th element, the first day, and access its lessons
const lessons = (await edulink_api.Timetable(tomorrow))[0].lessons;

console.log(lessons.map(lesson => [lesson.start_time, lesson.lesson_name]));
/*
[
  [ '08:40', 'English' ],
  [ '09:30', 'Biology' ],
  [ '10:20', 'Form Period' ],
  [ '10:50', 'Break' ],
  [ '11:20', 'History' ],
  [ '12:10', 'Mathematics' ],
  [ '13:00', 'Lunch' ],
  [ '13:55', 'D&T(Product)' ],
  [ '14:45', 'Computer Studies' ]
]
*/

Docs:

Documentation is still a work in progress, the documentation readme can be found in the modules.md file. Direct links to the documentation are also available below.

• Edulink_API class This is the main API interface, shown in the examples above.

  • Authenticate
  • Homework
  • Timetable

• Edulink_Raw class This class houses the raw requests to Edulink it can be used if you want more granular control over the requests, or if you want to use a feature that is not yet implemented.

  • Achievement
  • AchievementBehaviourLookups
  • Attendance
  • Behaviour
  • Catering
  • Clubs
  • Documents
  • Exams
  • ExternalLinks
  • Homework
  • Login
  • Logout
  • Personal
  • Ping
  • RegisterCodes
  • SchoolDetails
  • School_FromCode
  • Status
  • Timetable
  • initialize

• Edulink_Raw_Response_Types This module contains the response types that are returned by the Edulink API.

TODO:

• [ ] Add more examples
• [x] Document the API
• [ ] Add missing methods
• [x] Improve error messages
• [ ] Add missing return type properties, because of the way the types were created some properties that could be returned might not exist.
• [ ] I used the edulink DEMO when creating types and methods. This turns out to be really outdated and is missing a lot of properties. I will need to re do these types using the API with a real login.
• [x] Update examples
• [ ] Missing Homework Descriptions, some homeworks need an additional Homework_Details request to get the description.