Skip to main content

​
Overview

The room availability feature helps you find suitable classrooms based on course requirements, student capacity, and time constraints. The system applies multiple validation rules to ensure only compatible rooms are returned.

​
How It Works

When checking room availability, the system validates three main constraints:
  1. Capacity: Room must accommodate the number of students
  2. Compatibility: Room type must match course type (e.g., lab courses need lab rooms)
  3. Availability: Room must not be occupied or reserved at the requested time
The availability check considers all reservations regardless of semester, but you can filter results by semester.

​
Quick Start

1

Prepare Request Data

Gather the required information:
  • Course ID (e.g., A003)
  • Time slot (day, start time, end time)
  • Number of students
  • Semester
2

Send API Request

Call the /aulas-disponibles endpoint with your data
3

Review Results

Analyze available and unavailable rooms with rejection reasons

​
API Request

​
Endpoint

POST /aulas-disponibles

​
Request Body

curl -X POST http://localhost:8000/aulas-disponibles \
  -H "Content-Type: application/json" \
  -d '{
    "asignatura_id": "A003",
    "hora_inicio": "14:00",
    "hora_fin": "17:00",
    "dia": "Miércoles",
    "cantidad_estudiantes": 26,
    "semestre": 1
  }'

​
Request Parameters

ParameterTypeRequiredDescription
asignatura_idstringYesCourse identifier (e.g., “A003”)
hora_iniciostringYesStart time in HH:MM format (e.g., “14:00”)
hora_finstringYesEnd time in HH:MM format (e.g., “17:00”)
diastringYesDay of the week (Lunes, Martes, Miércoles, Jueves, Viernes, Sábado, Domingo)
cantidad_estudiantesintegerYesNumber of students (must be > 0)
semestreintegerYesAcademic semester (1-10)

​
Response Format

{
  "asignatura": {
    "id": "A003",
    "nombre": "Estructura de Datos",
    "tipo": "teorica"
  },
  "horario_solicitado": {
    "dia": "Miércoles",
    "hora_inicio": "14:00",
    "hora_fin": "17:00",
    "cantidad_estudiantes": 26,
    "semestre": 1
  },
  "aulas_disponibles": [
    {
      "id": "AU001",
      "nombre": "Aula 101",
      "tipo": "teorica",
      "capacidad": 40,
      "sede": {
        "id": "S001",
        "nombre": "Sede Central"
      },
      "recursos": [
        {
          "id": "R001",
          "nombre": "Proyector"
        },
        {
          "id": "R002",
          "nombre": "Pizarra Digital"
        }
      ]
    }
  ],
  "aulas_no_disponibles": [
    {
      "id": "AU002",
      "nombre": "Lab Computo 1",
      "razon": "El aula de tipo laboratorio no es compatible con la asignatura de tipo teorica"
    },
    {
      "id": "AU004",
      "nombre": "Aula 201",
      "razon": "Aula ocupada o reservada en el horario 14:00-17:00 el Miércoles"
    }
  ],
  "total_disponibles": 1,
  "total_no_disponibles": 2,
  "error": null
}

​
Understanding Rejection Reasons

​
Capacity Constraints

{
  "id": "AU002",
  "nombre": "Lab Computo 1",
  "razon": "Capacidad insuficiente: 25 lugares para 30 estudiantes"
}
The room doesn’t have enough seats for the number of students.
Always request rooms with a buffer. A room with exactly the same capacity might be uncomfortably full.

​
Compatibility Constraints

{
  "id": "AU002",
  "nombre": "Lab Computo 1",
  "razon": "El aula de tipo laboratorio no es compatible con la asignatura de tipo teorica"
}
The room type doesn’t match the course type:
  • Laboratorio courses require laboratorio rooms
  • Teorica courses can use teorica or hibrida rooms
  • Hibrida courses can use hibrida rooms

​
Availability Constraints

{
  "id": "AU001",
  "nombre": "Aula 101",
  "razon": "Aula ocupada o reservada en el horario 14:00-17:00 el Miércoles"
}
The room has an overlapping reservation or occupied slot.
Time slot conflicts are checked across all semesters. A room reserved in any semester for that time will be marked as unavailable.

​
Common Use Cases

​
Check Multiple Time Slots

To find the best available room, check multiple time slots: 
import requests

def find_best_room(course_id, students, day, semester):
    """Find the best available room by checking multiple time slots."""
    time_slots = [
        ("07:00", "09:00"),
        ("09:00", "12:00"),
        ("14:00", "17:00")
    ]
    
    results = []
    for start, end in time_slots:
        response = requests.post(
            "http://localhost:8000/aulas-disponibles",
            json={
                "asignatura_id": course_id,
                "hora_inicio": start,
                "hora_fin": end,
                "dia": day,
                "cantidad_estudiantes": students,
                "semestre": semester
            }
        )
        data = response.json()
        if data['total_disponibles'] > 0:
            results.append({
                "time_slot": f"{start}-{end}",
                "rooms": data['aulas_disponibles']
            })
    
    return results

# Usage
available_slots = find_best_room("A003", 26, "Lunes", 1)
for slot in available_slots:
    print(f"Time: {slot['time_slot']}")
    for room in slot['rooms']:
        print(f"  - {room['nombre']} (Capacity: {room['capacidad']})")

​
Filter by Campus/Sede

Filter available rooms by campus location: 
def get_rooms_by_sede(course_id, students, time_start, time_end, day, semester, sede_id):
    """Get available rooms filtered by campus."""
    response = requests.post(
        "http://localhost:8000/aulas-disponibles",
        json={
            "asignatura_id": course_id,
            "hora_inicio": time_start,
            "hora_fin": time_end,
            "dia": day,
            "cantidad_estudiantes": students,
            "semestre": semester
        }
    )
    
    data = response.json()
    # Filter by sede
    filtered_rooms = [
        room for room in data['aulas_disponibles']
        if room['sede']['id'] == sede_id
    ]
    
    return filtered_rooms

# Get only rooms in Sede Central
rooms = get_rooms_by_sede("A003", 26, "14:00", "17:00", "Miércoles", 1, "S001")
for room in rooms:
    print(f"{room['nombre']} at {room['sede']['nombre']}")

​
Check Required Resources

Verify that available rooms have required resources: 
def find_rooms_with_resources(course_id, students, time_start, time_end, day, 
                               semester, required_resources):
    """Find rooms that have all required resources."""
    response = requests.post(
        "http://localhost:8000/aulas-disponibles",
        json={
            "asignatura_id": course_id,
            "hora_inicio": time_start,
            "hora_fin": time_end,
            "dia": day,
            "cantidad_estudiantes": students,
            "semestre": semester
        }
    )
    
    data = response.json()
    suitable_rooms = []
    
    for room in data['aulas_disponibles']:
        room_resources = {r['id'] for r in room['recursos']}
        if set(required_resources).issubset(room_resources):
            suitable_rooms.append(room)
    
    return suitable_rooms

# Find rooms with projector and computers
rooms = find_rooms_with_resources(
    "A004", 25, "14:00", "17:00", "Viernes", 1, 
    required_resources=["R001", "R003"]  # Projector + Computers
)

​
Error Handling

import requests
from requests.exceptions import RequestException

def check_availability_safe(course_id, students, time_start, time_end, day, semester):
    """Check room availability with error handling."""
    try:
        response = requests.post(
            "http://localhost:8000/aulas-disponibles",
            json={
                "asignatura_id": course_id,
                "hora_inicio": time_start,
                "hora_fin": time_end,
                "dia": day,
                "cantidad_estudiantes": students,
                "semestre": semester
            },
            timeout=10
        )
        
        # Check for HTTP errors
        if response.status_code == 404:
            return {"error": "Course not found"}
        elif response.status_code == 400:
            return {"error": "Invalid request parameters"}
        elif response.status_code != 200:
            return {"error": f"Server error: {response.status_code}"}
        
        data = response.json()
        
        # Check for application-level errors
        if data.get('error'):
            return {"error": data['error']}
        
        return data
        
    except RequestException as e:
        return {"error": f"Network error: {str(e)}"}
    except ValueError as e:
        return {"error": f"Invalid JSON response: {str(e)}"}

# Usage
result = check_availability_safe("A003", 26, "14:00", "17:00", "Miércoles", 1)

if 'error' in result:
    print(f"Error: {result['error']}")
else:
    print(f"Found {result['total_disponibles']} available rooms")

​
Best Practices

Check Early

Check room availability well in advance to ensure you have options. Popular time slots fill up quickly.

Consider Buffer

Request rooms with 10-20% extra capacity for flexibility and comfort.

Multiple Options

Check multiple time slots and days to find the best fit for your schedule.

Verify Resources

Always verify that available rooms have the required equipment and resources.

​
Next Steps

Reserve a Room

Learn how to create reservations for available rooms

Constraint Validation

Understand how the validation chain works

Build docs developers (and LLMs) love

Get started for freeTalk to us