The Magic Behind UCL Library Seating
How UCL, and our API, seem to know everything.
There have been many questions over the past year or so about how UCL knows how full libraries are, and how they can tell you where to look for a seat. Here at UCL API, we also launched our Workspaces API, which can give you near-real-time availability data for almost every seat in every UCL library in JSON. You can even request maps of every library’s floor with each seat’s availability super-imposed as a Scalable Vector Graphic (SVG) that can be embedded into your apps. Cool, huh?
In this article I’ll explain the hardware that makes this happen, the rules in place (such as when a seat is truly free, which sounds rather philosophical now that I come to think of it), and how you can make use of this data in your apps.
The Hardware: OccupEye
The first step in making this happen is the provision of OccupEye devices distributed by a company known as Asure Software. Each of these little white sensor boxes are attached to the base of each desk, and they have an active internet connection that sends event updates to the OccupEye Cloud. Every event packet contains, amongst other metadata: the sensor’s ID, the timestamp of the event (i.e. when it happened) and whether the desk is now absent (i.e. free and available for somebody else to sit at) or occupied (i.e. in use). The sensor is also able to report other data such as its battery level so that failing sensors can be replaced or repaired in the field.
The Dashboard: OccupEye Online
All these sensors upload data constantly to the OccupEye Cloud. As the leader of UCL API, I have been granted access to the Dashboard that UCL Staff can use to constantly monitor libraries. The view available looks something like this:
Of course, all those charts and stats are unlikely to be particularly interesting to most students! However, it can be crucial to UCL’s professional services teams in ensuring that study spaces at UCL are both sufficient and well utilised. Furthermore, the data on this dashboard is actually more up to date than it should be. I’ll explain this in a moment…
The great thing about this OccupEye Cloud system is that it also has a documented API that we wrap around in UCL API; it is this data which feeds the /workspaces endpoints.
It is also through this data that UCL Assistant, a brand new (free!) app for helping you study at UCL, is able to show you live seat availability data.
Almost every library and study space at UCL has these sensors (which therefore shows the availability in the app), including the Student Centre, Main Library, Science Library, Cruciform Hub and even the Bartlett Library.
I Need to Pee! 🚾💦
Having live seat availability is great, but there are a few problems with this:
- What happens if you need to p̵e̵e̵ use the bathroom?! Should your seat now be available for anybody to use?
- What happens if your stand up to stretch?
- What if your feet move away from the sensor?
All these are very real issues with a sensor system like this, and it is addressed with UCL’s policy: essentially, your seat will not be marked as absent (and therefore available for another student) unless thirty minutes have passed since the notification from the sensor that the space is free. This lag is not enforced by the OccupEye service; instead, the UCL Library website adds this delay to each sensor before the final count is shown on the website, and for the UCL API we’ve written code which enforces this thirty minute delay at an API level. This means that when you consume the data, the seating counts should match UCL’s official seat availability numbers with this thirty minute grace period already accounted for.
In addition to this, all maps that are produced by the API take this thirty minute delay into account, so it is likely that some seats may be shown as taken even if nobody is sat there at the time for up to thirty minutes. This is also true for the live seating maps in UCL Assistant.
Muh Privacy!
Of course, with this many sensors across campus it’s easy to get concerned about privacy. The good news is that none of these sensors can personally identify any particular user, nor can we derive this information with what we have. Each sensor can only report on the state of the desk it is assigned to, and nothing else. The information is binary: either somebody has been sat there in the last thirty minutes, or they haven’t. We don’t know who that somebody is, nor can we identify if the person that is sat there now is different to the last time we checked the sensor’s status.
Performance
Dealing with data for thousands of library seats in real time could cause huge load issues. Therefore, instead of proxying every request through to OccupEye and calculating a response each time somebody asks, we cache the sensor states every two minutes from OccupEye into a bleeding fast in-memory Redis cache hosted on Amazon Web Services. Every night we do a larger operation in which we fetch a new list of libraries and rooms, fetch new maps and do general cleanup. This means that the data we provide is near-real-time, gets massaged with the thirty minute policy, and is served straight out of the cache when it’s requested in usually well under 300ms. We also pre-calculate a sensor summary that you can use to quickly show how many seats are available without having to request every sensor’s data; again, this is accurate to two minutes.
Historical Data
We also recognise that historical data can be really useful! This is used in UCL Assistant to show how busy each library is now compared to an average over the last month. Again, this data is available also through the UCL API, and is far beyond anything the UCL Libraries site can provide directly. It is also clean JSON, really clean JSON!
Any Questions?
Hit us up on Facebook, Twitter or by email: isd.apiteam [at] ucl.ac.uk. We can’t wait to see what you build!
