[DRAFT] New API
- Franco Reyes (Unlicensed)
Changes
/buildingsno longer returns image links/buildingsnow returns building coordinates
Add extra parameters to
/buildings/:building_idfor filters/buildings/:building_idnow only returns endtime if room status issoon
Replace
/buildings/:building_idendpoint with new/roomsendpoint that returns all rooms at once (grouped by building)Replace
/buildings/:building_id/:room_numberendpoint with new/rooms/:room_idendpoint that does the same thing but matches the/roomsendpoint’s nameOld endpoints won’t actually be removed until the frontend is changed to use the new endpoints
(TBD) Add a sorting parameter to
/buildings
(TBD) Add a new endpoint for searching
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.
API Documentation
/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 |
|---|---|
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.
},
...
]
} |
/rooms
Request Type: GET
Description
Retrieves the status and, if free soon, when it will be free for each room in the database.
The status is either free, soon or busy. soon is defined as the room being free within 15 minutes of the current time.
The time that the room is next free will be given in ISO form, namely YYYY-MM-DDTHH:mm:ss.sssZ. If the room is not free soon (i.e. status is free or busy), then the time will be an empty string.
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 |
|---|---|---|---|
datetime | String | A custom time and date in the 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 | status:FALSE |
location | String | One of | 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 |
|---|---|
200 | {
building_id: {
room_number: {
status: status of room,
endtime: if busy, when the room will be free
},
...
},
...
} |
400 | Invalid <parameter> |
/rooms/:room_id
Request Type: GET
Description
Retrieves the a list of room bookings for the given room ID and building ID
A booking is defined as follows
{
"course_code": the course code of the class in the room
"start": the starting time of the class in the format "HH:MM"
"end": the ending time of the class in the format "HH:MM"
}Path variables
Name | Description |
|---|---|
room_id | The ID of the required room e.g. K-J17-G01 |
Parameters
None
Result
week is a number starting from 1, represented as a string. day is a string denoting which day of the week it is, e.g. “Mon” or “Wed”
Code | Format |
|---|---|
200 | {
"roomName": the full name in words of the room e.g. Ainsworth G01
week: {
day: [
booking1,
booking2
],
...
},
...
} |
400 | Room ID <room_id> does not exist |
Data Sources
Timetable Data
The source of the timetable data is CSESoc’s timetable scraper. It is in the format below.
{
buildingID: {
roomID: {
"roomName": the name of the room e.g. Ainsworth 101,
week: {
day: [
{
"courseCode": the course code of the course e.g. COMP1511,
"start": the starting time of the class in 24-hour time,
"end": the ending time of the class in 24-hour time,
}
]
}
}
}
... more buildings follow on
}The keys buildingID, roomID, week and day are the literal values for that building code/room code/week of term/day of week. Day of the week is any string in the list ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
The keys in "" are fixed keys which do not change.
Building/Room Data
All the details of buildings/rooms found in database.json are scraped from the UNSW Learning Environments website: https://www.learningenvironments.unsw.edu.au/physical-spaces/teaching-spaces.