README

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

kataldeprecated

Usage no npm install needed!