Planifica API Documentation for School Schedule Optimization
Optimization Documentation
Planifica
Learn the core concepts, principles, and workflows behind intelligent schedule generation. Master the art of constraint-based optimization for educational timetables.
Core Concepts
Understanding the principles of constraint-based scheduling and quality optimization for educational timetables
Quality Optimization
Positions each course session in specific time slots and classrooms while maximizing schedule quality. The goal is to respect all constraints (room availability, teacher schedules, class availability) while placing sessions in their preferred time slots based on affinity weights.
Key Features:
- Complete timetable generation
- Time slot and room assignment
- Subject-specific time preferences
- Asynchronous processing
Constraint Management
Validates and manages all scheduling constraints including teacher availability, classroom capacity, grade working hours, and resource conflicts. Ensures all hard constraints are satisfied while optimizing soft constraints for quality.
Key Features:
- Teacher-to-session validation
- Resource feasibility checking
- Workload balancing
- Conflict resolution
Typical API Workflow
Submit Request
Send your school identifier plus course data, teachers, and constraints
Validate Constraints
Check model feasibility and constraints
Start Optimization
Launch asynchronous scheduling
Poll Status
Check progress and get final timetable
Pro Tip: Asynchronous Processing
Optimization can take time (30 seconds to 15 minutes depending on complexity). The API returns immediately with a job ID, then you poll the status endpoint until completion. This allows your application to remain responsive while processing happens in the background.
Required: School Identifier
Every request must include schoolExternalId and schoolName top-level fields — requests without them are rejected. See the API Reference for the full contract.
Understanding Constraints
Fine-tune your scheduling with powerful constraint types that deliver precise, high-quality timetables
Capacity Constraints
Define the maximum total hours a subject can have within a specific time period.
{
"subject": "MATH",
"capacity": 8,
"start_day": "monday",
"end_day": "friday"
}Result: Max 8 hours of Math per week
Cardinality Constraints
Define the maximum number of session blocks for a subject, regardless of duration.
{
"subject": "MATH",
"cardinality": 3,
"start_day": "monday",
"end_day": "friday"
}Result: Max 3 Math sessions per week
Preference Constraints
Soft constraints that assign scoring weights to optimize session placement in preferred time periods.
{
"subject": "MATH",
"preference_score": 9,
"start_time": "08:00",
"end_time": "11:00"
}Result: Prefer Math in morning hours (scale 1-10)
Note: Unlike hard constraints (Capacity/Cardinality), preference constraints are "soft" - they provide scoring bonuses to guide optimization rather than strict requirements that must be satisfied.
Capacity vs Cardinality: Understanding the Difference
Capacity (Hours-Based)
Definition: Total hours within time window
Example: "Max 6 hours of Physics per week"
2h + 2h + 2h = 6h total ✓
3h + 3h + 1h = 7h total ✗
Use Case: Workload management, curriculum hours
Cardinality (Session-Based)
Definition: Number of separate sessions
Example: "Max 3 Physics sessions per week"
Session 1 + Session 2 + Session 3 ✓
4 sessions (any duration) ✗
Use Case: Lab limitations, teacher availability
Session Ordering & Distance Constraints
Control the relative sequencing of sessions beyond plain time-slot requests by adding an ordering_configslist to a grade's schema.
follows
A session of subject_b must start exactly when a session of subject_a ends, same day.
{
"type": "follows",
"subject_a": "MATH",
"subject_b": "MATH_LAB"
}Result: The lab always immediately follows its lecture
avoid_after
No session of subject_b may be scheduled after a session of subject_a on the same day.
{
"type": "avoid_after",
"subject_a": "PE",
"subject_b": "MATH"
}Result: Math is never scheduled right after PE
distance_between
Keep two sessions at least min_gap_slots and/or at most max_gap_slots apart, in time slots.
{
"type": "distance_between",
"subject_a": "EXAM_PHYSICS",
"subject_b": "EXAM_CHEM",
"min_gap_slots": 4,
"direction": "both"
}Result: The two exams are spaced apart regardless of order
Note: Rules apply to every matching session of subject_a/subject_b by default — scope to one group with group, or to two exact sessions with session_a/session_b. Invalid configurations (cyclic follows chains, infeasible gaps, malformed distance_between rules) are rejected with a descriptive error before the solver runs.
Incremental Optimization: Locking Sessions
Re-optimize after a small change without reshuffling a published schedule
After a manual edit, a single teacher swap, or a small data change, you usually don't want the optimizer to move everything else. Pin a session by setting day and start on its ClassSessionentry — the solver will not move it, and re-optimizes everything else around it.
day + start only → time fixed, instructor & room still solver-decidedinstitutor → time and teacher fixed, room still solver-decidedclassroom too → fully fixed, the optimizer won't touch this session{
"id": "s1",
"day": "Monday",
"start": "09:00:00"
}Result: This session stays on Monday at 9:00, everything else re-optimizes around it
It's a pin, not a diff/patch: there's no previous_solution_id — resend day/start (and optionally institutor/classroom) from your last result on every request for any session you want kept in place.
Shared instructors propagate:locking one session's instructor auto-applies it to sibling sessions of the same grade/group/subject that don't specify one; locking two different instructors for the same group is rejected with a validation error.
No automatic consistency check: if availability or capacity changed since the original solve, a lock can make optimization fail or leave that session unallocated.
See Pinned Sessions below for a complete request example, including locking room and instructor together.
Optimization Objectives
Choose the right optimization strategy based on your educational priorities and constraints
TIME Optimization
Focuses on creating compact timetables by minimizing gaps and finishing days earlier.
Objectives:
- • Reduce empty periods in student/teacher schedules
- • Minimize overall schedule span
- • Create continuous time blocks
- • Optimize resource utilization
Best for: Schools prioritizing efficiency and early dismissals
AFFINITY Optimization
Maximizes schedule quality by placing sessions in their preferred time slots based on affinity weights.
Objectives:
- • Honor subject-specific time preferences
- • Optimize for learning effectiveness
- • Account for cognitive load patterns
- • Respect pedagogical best practices
Best for: Schools prioritizing educational outcomes and student performance
Optimization Configuration
Control when and how optimization terminates with intelligent stop conditions that balance quality, speed, and resource usage
Three Intelligent Stop Conditions
Time Limits
Hard deadline for optimization processing
Solution Limits
Control the number of solutions to explore
Quality Stops
Stop when improvements plateau
max_time_in_seconds
The primary stop condition that sets a hard time limit. The optimizer will return the best solution found within this timeframe.
{
"config": {
"max_time_in_seconds": 300,
"objective_type": "TIME"
}
}Best for: Production: 60-300s, Batch processing: 600-1200s
max_solutions
DeprecatedNo longer configurable. The optimizer always runs until max_time_in_seconds or no_improvement_timeout_seconds is reached. The field is still type-checked as an optional integer (1–30) when present, so omitting it or sending max_solutions: null is always safe, but an out-of-range integer still returns a validation error. Remove it from new integrations.
no_improvement_timeout_seconds
Stops optimization if no better solution is found within the specified time period. This prevents continued processing when improvements have plateaued.
Configuration Example
{
"config": {
"no_improvement_timeout_seconds": 60,
"use_objective": true,
"objective_type": "AFFINITY"
}
}Use Cases: Quality-focused optimization, resource conservation, preventing local optima
Pinned Sessions
Pre-position critical sessions before optimization
What are Pinned Sessions?
Sessions that are fixed in specific time slots, instructors, or classrooms before optimization begins. The scheduler treats these as immovable constraints and builds the rest of the timetable around them.
Example Configuration
{
"session": "CHEM_LAB_001",
"duration": 120,
"subject": "CHEMISTRY",
"day": "tuesday",
"start": "14:00",
"institutor": 15,
"classroom": 8
}Result: Chemistry lab with Dr. Johnson in Lab Room 8, every Tuesday at 2:00 PM
Use Cases: Shared facilities, external instructors, administrative periods, special events
Ready to Start Building?
Now that you understand the concepts, explore the technical reference and get API access to start implementing.
Next Steps
Continue your journey with these related resources