katal v9.6.2
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 abovegetAbsences
- Note thatAbsence-Statistics
are in a seperate file.getAbsencesStatistics
- Note thatAbsence by period
are in a seperate file.getTimeTable
- Get this- & next week's Timetable.getDetails
- Get Personal Details about student.getResults
- Note thatOfficialResults
&NCEASummary
are both in seperate files.getNCEASummary
- Note thatOfficialResults
&Results
are both in seperate files.getEndorsements
- (OfficialResults
) Note thatNCEASummary
&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
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago