IlliniSpots is a web application that helps UIUC students find available study spaces and classrooms across campus in real-time. The app shows building availability on an interactive map and provides detailed room status information.
- Interactive campus map showing buildings with available rooms
- Real-time room availability status
- Detailed information for each building including:
- Number of available/occupied rooms
- Current classes in session
- Upcoming class schedules
- Room availability times and length
- Integration of updated daily events for a comprehensive and up-to-date view of room usage
- Library-specific features:
- Real-time study room availability
- Reservation slot visualization
- Direct reservation links
- Room images and details
- Responsive design for both desktop and mobile
- Next.js
- React (memo, hooks)
- TypeScript
- Tailwind CSS
- shadcn/ui
- MapLibre GL JS (with special thanks to openfreemap and its creator Zsolt Ero for providing free map tiles)
- Supabase (PostgreSQL database)
- Next.js API Routes
- PostgreSQL Functions (for
get_current_building_status)
All data used for calculating room availability is sourced from the University of Illinois at Urbana-Champaign's official resources:
- Class Data: Sourced from the Course Explorer. This includes information about when classes meet, which is used to determine room occupancy. For more details on the data collection process, please refer to the data-pipeline README.
- Building Hours: Sourced from the Facility Scheduling and Resources.
- Library Data: Sourced from UIUC Library's Room Reservation System.
- Daily Events: Sourced from the Tableau Daily Event Summary.
The availability logic is handled by a PostgreSQL function that processes building and room status through three main stages:
- State Detection
- How: Uses a series of CTEs that join current time against class_schedule and daily_events tables
- Implementation: First maps day codes (M-U) to hours via CASE statements, then performs time window overlap with check_time
current time (3:15 PM) → finds active classes/events → determines if room occupied
Example: Room 101 has class 3:00-4:00 PM = occupied
- Gap Analysis
- How: Recursive CTE traverses chronologically sorted class/event times
- Implementation: For each room:
- Starts at first available time
- Checks interval to next class/event
- If gap >= minimum_useful_minutes (configured at 30), marks as available period
- Repeats until finding valid gap or reaching building close
Example: 3:00-4:00, 5:00-6:00
Gap found: 4:00-5:00 (60min) = valid gap > minimum_useful_minutes
- Duration Calculation
- How: Epoch time arithmetic between current_time and next constraint
- Implementation: Takes earliest of:
- Next class/event start time
- Building closure time
- End of current gap
Example: Current 3:15, Next class 4:00
Duration = (4:00 - 3:15) = 45 minutes available
{
"timestamp": "2024-10-29T14:30:00Z",
"buildings": {
"David Kinley Hall": {
"name": "David Kinley Hall",
"coordinates": {
"latitude": 40.10361941,
"longitude": -88.22835896
},
"hours": {
"open": "07:00:00",
"close": "23:59:00"
},
"isOpen": true,
"roomCounts": {
"available": 15,
"total": 28
},
"rooms": {
"106": {
"status": "occupied" | "available",
"available": false,
"currentClass": {
"course": "PS 318",
"title": "Interests Grps & Soc Movements",
"time": {
"start": "11:00:00",
"end": "12:20:00"
}
},
"nextClass": {
// same structure as currentClass
},
"passingPeriod": false,
"availableAt": "15:30",
"availableFor": 60, // minutes
"availableUntil": "16:30"
}
// ... more rooms
}
}
// ... more buildings
}
}
The library availability system operates through a three-stage pipeline handling UIUC's LibCal reservation data:
- Room Data Extraction
- Scrapes LibCal's client-side JavaScript resource declarations using regex pattern matching
- Extracts embedded room metadata including IDs, capacities, and asset URLs
- Maps rooms to their parent libraries using facility IDs
- Reservation Status Collection
- Sends concurrent POST requests to LibCal's availability grid endpoint for each library
- Special case for Funk ACES (room reservation closes at 2 AM): Retrieves 48hr window vs standard 24hr
- Accumulates slot data chronologically with booking status flags
- Availability Processing
- Links room metadata with current reservation states
- Calculates real-time metrics per room:
- Current occupancy status
- Time until next available slot
- Duration of current available period
- Chronological sequence of free/busy periods
- Aggregates library-level statistics (total rooms, currently available)
- Node.js 18.17 or later
- npm or yarn
- Supabase account
- Clone the repository:
git clone https://github.com/plon/illinispots- Install dependencies:
cd illinispots
npm install- Set up environment variables:
Create a
.env.localfile with the following:
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_key- Run the development server:
npm run devOpen http://localhost:3000 to view the app.
- Building/room access may be restricted to specific colleges or departments
- Displayed availability only reflects official class schedules
- Rooms may be occupied by unofficial meetings or study groups
- Different schedules may apply during exam periods
This project was inspired by Spots, a similar service for University of Waterloo students.
This project is licensed under the MIT License - see the LICENSE file for details.