Create an app using the UCL API free rooms endpoint
We have just launched a new free rooms endpoint uclapi.com/roombookings/freerooms in our Room Bookings API and we wanted to show you how easy it is to create a web application using it.
In this tutorial, we will be creating a very simple application that shows all the rooms currently free in UCL. This what the final application will look like.
Step 1: Create a new app on your dashboard.
Go to uclapi.com/dashboard, sign in, and click the big blue button to create a new app. Give it any name you like and click “Create”.
We’ll need this app to get an API token which we’ll use to call the free rooms endpoint.
Step 2: Set up Glitch
Once this is done, click the link below to create your own Glitch app.
Glitch is the friendly community where you’ll build the app of your dreams
You should see something like the image below.
Glitch allows us to code our application without having to worry about deploying it. After we finish, it also allows us to see a live preview of our application.
In the Glitch app, we have set up the HTML and CSS files for you already. We will now fill out the script.js to make calls to the free rooms endpoint.
We’ll be using jQuery to call the API and to dynamically add elements to our HTML page.
Step 3: Set up the parameters
Our app will show users all the current free rooms at UCL. Let’s get started by setting up the parameters. The free rooms endpoint requires three params ( token , start_time , end_time ).
token is the API access token you get from the app on your UCL API dashboard that you created in Step 1.
start_time is the ISO formatted start time you want to find free rooms for.
end_time is the minimum time until which the requested rooms should be free.
Now lets add the first lines of code in our script.js file. (Don’t forget to replace <your token here> with your access token from your UCL API dashboard).
let token = "<your token here>";let now = new Date();
let currentTime = now.toISOString();now.setHours(now.getHours()+1); // move forward one hour
let endTime = now.toISOString();let url = "https://uclapi.com/roombookings/freerooms"
let params = {
token: token,
start_datetime: currentTime,
end_datetime: endTime
}
In the code we’re first getting the current time using JavaScript’s date object and then getting an ISO string representation of it by calling the .toISOString() method on it.
We then set up the parameters that we will need to pass to our API call.
Step 4: Call Free Rooms Endpoint
Having set up the parameters, let’s now call the API. We’ll be using jQuery’s get call as below.
$.get(url, params, function(data) {
if (data["ok"]) {
data["free_rooms"].forEach(addRoom);
}
else {
$("#rooms").append("Can't find any free rooms now.");
}
});The $.get() calls our endpoint (stored in the url variable) with all the params, and stores the response in the data variable.
An example response from the free rooms endpoint looks as below.
{
"ok": true,
"free_rooms": [
{
"siteid": "014",
"location": {
"address": [
"Gower Street",
"London",
"WC1E 6BT",
""
],
"coordinates": {
"lat": 51.23412,
"lng": 51.23123
}
},
"classification": "ER",
"sitename": "Front Lodges",
"roomname": "North Lodge 001",
"automated": "N",
"roomid": "001",
"capacity": 10
},
...
]
}So in the get call, we then check to see if the response was successful by checking the value of data["ok"] .
If we are successful, we then loop over the free_rooms array and call the addRoom function on each element. We’ll now define the addRoom function as below.
function addRoom(room) {
let latitude = room["location"]["coordinates"]["lat"];
let longitude = room["location"]["coordinates"]["lng"];
let mapsLink = `http://maps.google.com/maps?q=${latitude},${longitude}`;
$("#rooms").append(
`<div class="room">
<a href=${mapsLink}>${room["roomname"]}</a>
<p>Capacity: <b>${room["capacity"]}</b></p>
</div>`
);
}In the addRoom function, we get the details of the room which we use to create a div . We simultaneously add this new div into a div with id rooms in our HTML file.
The `${..}` is a new feature of JavaScript called template literals. They basically substitute the value of the variable, inside the braces, into the outer string. For example, in the `mapsLink`variable, `${latitude}` will be replaced with the value of the variable `latitude`.
Finally, this is what the complete script.js file looks like.
let token = "<your token here>"let now = new Date();
let currentTime = now.toISOString();now.setHours(now.getHours()+1); // move forward one hour
let endTime = now.toISOString();let url = "https://uclapi.com/roombookings/freerooms"
let params = {
token: token,
start_datetime: currentTime,
end_datetime: endTime
}$.get(url, params, function(data) {
if (data["ok"]) {
data["free_rooms"].forEach(addRoom);
}
else {
$("#rooms").append("Can't find any free rooms now.");
}
});function addRoom(room) {
let latitude = room["location"]["coordinates"]["lat"];
let longitude = room["location"]["coordinates"]["lng"];
let mapsLink = `http://maps.google.com/maps?q=${latitude},${longitude}`;
$("#rooms").append(
`<div class="room">
<a href=${mapsLink}>${room["roomname"]}</a>
<p>Capacity: <b>${room["capacity"]}</b></p>
</div>`
);
}
Step 5: Enjoy your newly created free room finder
Now click on the ‘Show Live’ button on Glitch.
This should open up a new tab with your ‘UCL Free Room Finder’.
Next Steps
As you can see, the free rooms endpoint makes it very easy to find all free rooms without you having to request all available rooms and parsing through the data to find which one’s are free in the given time range.
Now that you know how to use the free rooms endpoint, you might want to expand the application. One idea is to get a minimum capacity the user requires for the rooms and then use that to limit the rooms you show. The free rooms endpoint takes in a lot of additional query parameters, which you can use to filter the data you get.
We look forward to seeing how you will use the free rooms endpoint in your applications.
We’re here to help! If you’re stuck or encounter any problems, comment on here, email us, tweet at us, or send us a message on facebook.
