This package has been deprecated

Author message:

This package is deprecated

katal

KAMAR API (project katal)

🏫 📚 🎓 🥝 Unofficial node.js module for interfacing with the undocumented KAMAR API (project katal).

Install

npm i -S katal

Usage

var katal = require('katal');
var KAMAR = new katal({
  portal: 'student.kamar.nz'
});

The options can include:

Parameter	Description	Default	Required
portal	The url of the portal, excluding https?:// and /api/api.php.		Yes
year	The year to use, otherwise current year is used.	2017
TT	the Timetable Grid to lookup Timetable and Absences by. Leave blank unless you understand how grids work.	year + 'TT'
UserAgent	The UserAgent to use for HTTP requests to the KAMAR portal.	"Katal API for KAMAR v???? (Cargo 3.69) [http://git.io/katal]"
timezone	The timezone to use for timetables.	"Pacific/Auckland"
calendar	The calendar.json file got from KAMAR.getCalendar().		Yes for timetable
useHTTP	if true, HTTP will be used instead of HTTPS, which is a potential security risk.	false
exponentialBackoff	if true, requests failed due to timeout will be backed off exponentially.	false
timeout	timeout for HTTP requests in ms.	10000

Authenticating

KAMAR
  .authenticate({
    username: 15999,
    password: 'xxxxxxxx'
  })
  .then(function (credentials) {
    //execute other commands with credentials
  })
  .catch(function (error) {
    //deal with errors
  });

This yields an object containing username, key & authLevel.
authLevel is a number which distinguishes teachers and students. This is different for each school. (e.g. 0 = not logged in, 1 = students, 2 = primary caregiver, 3 = secondary caregiver, 10 = teacher, 23 = admin...)

Fetching Files

All methods return promises, so they can easily be linked together for complex queries.

KAMAR
  .get______(credentials) //credentials is the object returned by KAMAR.authenticate 
  .then(function (response) {
    //do stuff with response
  })
  .catch(function (error) {
    //deal with errors
  });
 

Methods

• authenticate - see above
• getAbsences - Note that Absence-Statistics are in a seperate file.
• getAbsencesStatistics - Note that Absence by period are in a seperate file.
• getTimeTable - Get this- & next week's Timetable.
• getDetails - Get Personal Details about student.
• getResults - Note that OfficialResults & NCEASummary are both in seperate files.
• getNCEASummary - Note that OfficialResults & Results are both in seperate files.
• getEndorsements - (OfficialResults) Note that NCEASummary & Results are both in seperate files.
• getGroups - get Student Groups (co-curricular and school-based).
• getAwards - get Student Awards.

---

• searchStudents - Note that you need to be authenticated with a user who has permission to do this.

---

• sendCommand - send a command to KAMAR - Note that more convenient methods exist for common files.

---

• makevCardFromDetails - convert Details to vCard (VCF) format.
• makeASCIItableWithAbsences - convert Absences to ASCII table (TXT) format.

See the Example Responses and the FileName rules (for the getFile query)

Example

var katal = require('katal'),
    KAMAR = new katal({ portal: 'student.kamar.nz' });
 
KAMAR
  .authenticate({ username: 'web.student', password: 'student' })
  .then(credentials => KAMAR.getAbsences(credentials))
  .then(absences => {
    console.log(absences);
  })
  .catch(error => console.error(error));

See example.js or try it in your browser on runkit.com

low-level KAMAR API

The low-level, XML-based API has been (unofficially) documented in the following file: KAMAR API Docs