/
Backend Server API

Backend Server API

Owned by Mun Joon Teo (Unlicensed)
Last updated: Sept 20, 2023 by Franco Reyes (Unlicensed)
4 min read

Naming Conventions

buildingID - the campus and grid reference of the building, e.g. K-J17

The first character denotes which campus the building is located in, with K standing for the Kensington campus. The string after the dash denotes the grid reference of the building, according to the campus map. Hence, the above ID refers to the building located at grid reference J17 of the Kensington campus, namely the Ainsworth building.

roomNumber - the room number only e.g. G01

The first character of the code is the floor of the building and the following characters are the room number. Hence the above room is the first room on the ground floor.

roomID - the campus, grid reference of the building and the room number e.g. K-J17-G01

The building ID of the room’s building and the room number joined with a dash.

Date and Time Formats

To avoid any ambiguity, datetimes in the API are always in ISO Format. This is the time in the format YYYY-MM-DDTHH:MM:SS.sssZ.

Note that the Z signifies UTC time, so all datetimes passed are expected to be correct UTC time. This means that 3:47 pm on the 29th of May in Sydney time should be 2023-05-29T05:47:00.000Z, not 2023-05-29T15:47:00.000Z.

In JavaScript, the conversion to UTC and formatting can be obtained using the .toISOString() method (docs) and can be parsed by the builtin Date object parsers (new Date(string) or Date.parse(string)).

API Documentation

/api/buildings

Request Type: GET

Description

Retrieves a list of all buildings at UNSW. Each building has a name, ID and coordinates.

Parameters

None

Result

Code

Format

Code

Format

200

{ "buildings": [ { "name": full name in words e.g. Ainsworth Building, "id": building ID e.g. K-J17, "lat": latitude of the building to 6 d.p., "long": longitude of the building to 6 d.p., "aliases": [other names of building] }, ... ] }

/api/rooms

Request Type: GET

Description

Retrieves an object containing all rooms at UNSW. The object maps room IDs to room data. Room data includes room name, room ID, usage, capacity (and also aliases and the school that manages it).

Parameters

None

Result

Code

Format

Code

Format

200

{ "rooms": { room_id: { "name": full name in words e.g. Brass Lab J17 305, "id": room ID e.g. K-J17-305, "abbr": abbreviated name on timetable e.g. BrassME305, "usage": type of room e.g. CMLB (computer lab), "capacity": number of seats e.g. 36, "school": school that manages the room e.g. COMPSC }, ... } }

/api/rooms/status

Request Type: GET

Description

Retrieves the status of all rooms.

The status is either free, soon or busy. soon is defined as the room being free within 15 minutes of the current time.

The endtime field contains a date in ISO format. What it represents depends on the status of the room:

  • If the status is free, then endtime is when it will next be busy. If the room is free for the rest of the day, endtime is an empty string.

  • If the status is busy, then endtime is when it will next be free.

  • If the status is soon, then endtime is when it will next be free (which should be within 15 minutes).

The returned rooms are grouped by building, identified by the building ID (e.g. K-J17), and each room is identified by its room number (e.g. G01).

If a datetime is provided, the status during the provided time and date for each room will be returned. Otherwise, the status of rooms at the current time is returned.

If filter parameters are provided, any rooms that do not meet the filter are not returned.

Parameters

Key

Type

Description

Required

Key

Type

Description

Required

datetime

String

A custom time and date in ISO format.

status:FALSE

capacity

Integer

Minimum room capacity.

status:FALSE

duration

Integer

Minimum duration that the room should be free for in minutes.

status:FALSE

usage

String

One of:

  • "AUD" - Auditorium

  • "CMLB" - Computer Lab

  • "LAB" - Lab

  • "LCTR" - Lecture Hall

  • "MEET" - Meeting Room

  • "SDIO" - Studio

  • "TUSM" - Tutorial Room

status:FALSE

location

String

One of "upper" or "lower".

status:FALSE

Result

The returned object maps building IDs to an object containing the status of its rooms, which consists of key-value pairs where the key is the room ID and the value is its status.

Code

Format

Code

Format

200

{ building_id: { room_number: { "status": status of room, "endtime": when the current status ends }, ... }, ... }

400

Invalid <parameter>

/api/rooms/bookings/:room_id

Request Type: GET

Description

Retrieves the a list of room bookings for the given room ID.

A booking is defined as follows

{ "name": the name of the group or event this booking is for "bookingType": the type of booking e.g. "CLASS" or "SOCIETY" "start": the starting time of the class "end": the ending time of the class }

Path variables

Name

Description

Name

Description

room_id

The ID of the required room e.g. K-J17-G01

Parameters

None

Result

Code

Format

Code

Format

200

{ "bookings": [bookings as defined above] }

400

Room ID <room_id> does not exist

Data Sources

The details of all rooms and buildings as well as the bookings for each room are scraped from the UNSW Timetable Enquiry website: https://nss.cse.unsw.edu.au/tt/

Related content