Skip to main content

​
Finding Your First Empty Classroom

This guide will walk you through using EmptyClassroom to find available study spaces at Boston University.
1

Visit EmptyClassroom

Navigate to emptyclassroom.com in your web browser.The homepage displays:
  • Last Updated Time: When classroom data was last refreshed
  • Refresh Button: Manually update availability (30-minute cooldown)
  • Building List: All CAS and CGS buildings with real-time availability counts
2

View Available Classrooms

Each building shows its current availability status:
// Buildings display format
"College of Arts & Sciences - CAS"
Status: "5 available" (green) or "unavailable" (red)
Click on any building to expand and see detailed classroom availability.
The availability count updates automatically every minute based on the current time.
3

Check Time Slots

When you expand a building, you’ll see all classrooms with their available time slots:
CAS 116                  🟢  9:00 AM - 11:00 AM
                             2:00 PM - 5:00 PM
                             7:00 PM - 11:00 PM
  • Green dot (🟢): Currently available
  • Red dot (🔴): Currently occupied
  • Green time: Current active time slot
  • Gray time: Future available slots
Time slots update in real-time as you browse.
4

Search for Specific Rooms

Use the search bar to quickly find classrooms:
Search: "CAS"
Results: All College of Arts & Sciences classrooms
The search matches building codes, room numbers, and full building names. It works with or without spaces between the building code and room number.

​
Understanding the Interface

​
Classroom Display

Here’s how classroom information is structured: 
// Classroom component structure from BuildingAccordion.tsx
<div className="classroom-item">
  <div className="flex items-center justify-between">
    <span className="font-mono">CAS 116</span>
    <div className={available ? 'bg-green-500' : 'bg-red-500'} />
  </div>
  {classroom.availability.map(slot => (
    <div className={isActive ? 'text-green-600' : 'text-gray-700'}>
      {formatTime(slot.start)} - {formatTime(slot.end)}
    </div>
  ))}
</div>

​
Availability Colors

  • Green Badge: Room is currently available (has at least one active time slot)
  • Red Badge: Room is currently occupied or has no available slots
  • Green Text: This time slot is active right now
  • Gray Text: Future time slot (not yet active)

​
Refreshing Data

​
Manual Refresh

Click the ↻ Refresh button to fetch the latest classroom availability from BU’s scheduling system.
Refresh Cooldown: To prevent server overload, refreshes are limited to once every 30 minutes. The button will show remaining wait time during cooldown.

​
How Refresh Works

# backend/main.py:74-100
@app.post('/api/refresh')
async def refresh_data():
    # Check cooldown period
    if time_since_refresh < timedelta(minutes=REFRESH_COOLDOWN_MINUTES):
        raise HTTPException(
            status_code=429,
            detail=f"Please wait {remaining_minutes:.1f} more minutes."
        )
    
    # Fetch fresh data
    await update_cache()
    
    # Update timestamp
    now = datetime.now(pytz.timezone('America/New_York'))
    rd.set('classrooms:last_refresh', now.isoformat())
    
    return {"timestamp": now.isoformat()}

​
Automatic Updates

  • Time Display: Updates every minute automatically
  • Current Availability: Recalculates which rooms are available based on current time
  • Data Freshness: Backend fetches new data on app startup if data is stale

​
Search Features

​
Smart Matching

The search implementation from SearchBar.tsx and BuildingAccordion.tsx: 
// frontend/app/components/BuildingAccordion.tsx:101-124
const matchesSearch = (building: Building, code: string, classroom?: Classroom) => {
  const query = searchQuery.toLowerCase().trim();
  if (!query) return true;

  if (classroom) {
    const withSpace = `${code} ${classroom.name}`.toLowerCase();
    const withoutSpace = `${code}${classroom.name}`.toLowerCase();
    return (
      withSpace.includes(query) ||
      withoutSpace.includes(query) ||
      building.name.toLowerCase().includes(query)
    );
  }

  return (
    code.toLowerCase().includes(query) ||
    building.name.toLowerCase().includes(query) ||
    building.classrooms.some(room => {
      const withSpace = `${code} ${room.name}`.toLowerCase();
      const withoutSpace = `${code}${room.name}`.toLowerCase();
      return withSpace.includes(query) || withoutSpace.includes(query);
    })
  );
};

​
Search Examples

Input: "CAS"
Matches: All 50+ CAS classrooms

​
Important Notes

Building Access: Some rooms may be restricted to specific colleges or departments. Check building access policies before heading to a classroom.
Unofficial Use: Displayed availability only reflects official schedules. Rooms may be occupied by study groups or unofficial meetings.
Minimum Time Slots: Only gaps of 30+ minutes are shown to ensure meaningful study time.

​
Next Steps

Building Details

Learn about operating hours and specific classrooms in each building

API Reference

Integrate EmptyClassroom data into your own applications

Submit Feedback

Request features or report issues

View Source Code

Contribute to the project on GitHub

​
Troubleshooting

​
No Classrooms Showing

If you see “Loading data…” for an extended period:
  1. Check your internet connection
  2. Try refreshing the page
  3. Clear browser cache and reload

​
Refresh Button Disabled

The refresh button may be disabled if:
  • A refresh was performed in the last 30 minutes (cooldown active)
  • Data is currently being refreshed (shows “Refreshing…”)
  • The system is checking cooldown status
Hover over the disabled button to see the remaining cooldown time.

​
Search Not Working

If search isn’t returning expected results:
  • Check spelling of building codes (CAS, CGS)
  • Try searching without spaces (e.g., “CAS116” instead of “CAS 116”)
  • Search is case-insensitive, so “cas” works the same as “CAS”

​
Pro Tips

Best Study Times: Late afternoons (4-6 PM) and evenings (7-9 PM) typically have the most available classrooms as scheduled classes wind down.
Plan Ahead: Check future time slots to plan your study session. Green text indicates the current slot, while gray text shows upcoming availability.
Multiple Options: If your first choice is occupied, the search function makes it easy to quickly find alternatives in the same building.

Build docs developers (and LLMs) love

Get started for freeTalk to us