Real-Time Scheduling

Real-time scheduling enables you to maintain optimal routes throughout the day by combining comprehensive morning planning with rapid on-the-fly adjustments. This two-phase approach handles both strategic daily planning and tactical real-time responses to changing conditions.

How Real-Time Scheduling Works

Real-time scheduling leverages two different solve endpoints to balance comprehensive optimization with speed:

Phase 1: Morning Bulk Optimization

Start each day with comprehensive planning using the asynchronous solve endpoint:

Bulk Problem Setup

Prepare your complete daily schedule with all known jobs, resources, and constraints.

{
  "jobs": [
    {"name": "delivery_001", "location": [4.3517, 50.8503], "duration": 1800},
    {"name": "delivery_002", "location": [2.3522, 48.8566], "duration": 1200},
    // ... 200+ more jobs
  ],
  "resources": [
    {"name": "driver_1", "start": [4.3517, 50.8503]},
    {"name": "driver_2", "start": [4.3517, 50.8503]},
    // ... additional resources
  ]
}

Comprehensive Solve

Submit to the asynchronous solve endpoint for thorough optimization.

POST /v2/vrp/solve

This takes 2-5 minutes but produces the highest quality solution considering all constraints and optimization objectives.

Extract Schedule Foundation

Use the complete solution as your baseline schedule for the day.

{
  "routes": [
    {
      "resourceId": "driver_1",
      "jobs": [
        {
          "jobId": "delivery_001",
          "arrival": "2024-03-15T09:15:00Z",
          "departure": "2024-03-15T09:45:00Z"
        },
        {
          "jobId": "delivery_002", 
          "arrival": "2024-03-15T11:30:00Z",
          "departure": "2024-03-15T11:50:00Z"
        }
      ]
    }
  ]
}

Phase 2: Real-Time Adjustments

Throughout the day, use the synchronous endpoint for rapid schedule updates:

Current State Capture

When changes occur, capture the current schedule state using initialResource and initialArrival fields.

{
  "jobs": [
    {
      "name": "delivery_001",
      "initialResource": "driver_1",
      "initialArrival": "2024-03-15T09:15:00Z",
      "location": [4.3517, 50.8503],
      "duration": 1800
    },
    {
      "name": "new_urgent_job",
      "priority": 100,
      "urgency": 100,
      "location": [3.0686, 50.6365],
      "duration": 900,
      "windows": [{"from": "2024-03-15T10:00:00Z", "to": "2024-03-15T12:00:00Z"}]
    }
  ]
}

Rapid Re-optimization

Submit to the synchronous solve endpoint for immediate results.

POST /v2/vrp/sync/solve

Returns optimized solution in seconds, building on the initial state.

Deploy Updated Schedule

Immediately deploy the updated routes to your field teams.

Synchronous solve completes in under 5 seconds, enabling real-time responsiveness.

Key Schema Fields for Real-Time Scheduling

The VRP solver provides specific fields designed for real-time operations:

Initial State Fields

Use these fields to provide the current schedule state to the solver:

initialResource
initialArrival

{
  "name": "delivery_001",
  "initialResource": "driver_1",
  "location": [4.3517, 50.8503],
  "duration": 1800
}

Purpose: Warm start optimization by indicating which resource is currently assigned to each job.Usage: Set based on your current schedule to help the solver understand the starting point.

{
  "name": "delivery_001", 
  "initialResource": "driver_1",
  "initialArrival": "2024-03-15T09:15:00Z",
  "location": [4.3517, 50.8503],
  "duration": 1800
}

Purpose: Indicates the currently planned arrival time for the job.Usage: Helps the solver understand timing constraints and minimize disruption to existing schedules.

Planned State Fields

Use these fields to create soft constraints around customer commitments:

plannedResource
plannedArrival

{
  "name": "customer_appointment",
  "plannedResource": "technician_2",
  "plannedArrival": "2024-03-15T14:00:00Z",
  "location": [2.3522, 48.8566],
  "duration": 3600
}

Purpose: Creates a hard constraint that this job must be assigned to the specified resource.Usage: Use for confirmed customer appointments or resource-specific requirements.

{
  "name": "customer_appointment",
  "plannedArrival": "2024-03-15T14:00:00Z",
  "location": [2.3522, 48.8566], 
  "duration": 3600
}

Purpose: Creates a soft constraint encouraging the solver to schedule near this time.Usage: Represents customer appointment times while allowing flexibility for optimization.

Real-Time Scheduling Patterns

Pattern 1: New Job Insertion

Add urgent jobs to the current schedule:

{
  "jobs": [
    // Existing jobs with current state
    {
      "name": "existing_001",
      "initialResource": "driver_1", 
      "initialArrival": "2024-03-15T09:15:00Z",
      "location": [4.3517, 50.8503],
      "duration": 1800
    },
    {
      "name": "existing_002",
      "initialResource": "driver_1",
      "initialArrival": "2024-03-15T11:30:00Z", 
      "location": [2.3522, 48.8566],
      "duration": 1200
    },
    // New urgent job
    {
      "name": "urgent_repair",
      "priority": 100,
      "urgency": 100,
      "location": [3.0686, 50.6365],
      "duration": 900,
      "windows": [{"from": "2024-03-15T10:00:00Z", "to": "2024-03-15T12:00:00Z"}]
    }
  ],
  "resources": [
    {"name": "driver_1", "start": [4.3517, 50.8503]}
  ]
}

Pattern 2: Job Cancellation

Remove cancelled jobs and reoptimize remaining schedule:

{
  "jobs": [
    // Keep only non-cancelled jobs
    {
      "name": "delivery_001",
      "initialResource": "driver_1",
      "initialArrival": "2024-03-15T09:15:00Z",
      "location": [4.3517, 50.8503],
      "duration": 1800
    }
    // delivery_002 removed due to cancellation
  ],
  "resources": [
    {"name": "driver_1", "start": [4.3517, 50.8503]}
  ]
}

Pattern 3: Resource Unavailability

Handle driver breaks, vehicle issues, or other resource constraints:

{
  "jobs": [
    {
      "name": "delivery_001",
      "initialResource": "driver_2",  // Reassigned from driver_1
      "location": [4.3517, 50.8503],
      "duration": 1800
    },
    {
      "name": "delivery_002",
      "location": [2.3522, 48.8566],
      "duration": 1200
      // No initial assignment - solver will assign to available resource
    }
  ],
  "resources": [
    // driver_1 removed due to unavailability
    {"name": "driver_2", "start": [3.0686, 50.6365]}
  ]
}

Pattern 4: Customer Rescheduling

Handle customer-requested appointment changes:

{
  "jobs": [
    {
      "name": "customer_appointment",
      "plannedArrival": "2024-03-15T16:00:00Z",  // Moved from 14:00
      "location": [2.3522, 48.8566],
      "duration": 3600,
      "windows": [{"from": "2024-03-15T15:00:00Z", "to": "2024-03-15T17:00:00Z"}]
    },
    // Other jobs with current initial state
    {
      "name": "delivery_001",
      "initialResource": "driver_1",
      "initialArrival": "2024-03-15T09:15:00Z",
      "location": [4.3517, 50.8503],
      "duration": 1800
    }
  ],
  "resources": [
    {"name": "driver_1", "start": [4.3517, 50.8503]}
  ]
}

Implementation Architecture

Backend Integration

Structure your real-time scheduling system with clear separation between bulk and real-time operations:

class RealtimeScheduler {
  async performMorningOptimization(jobs, resources) {
    // Use async solve for comprehensive optimization
    const response = await fetch('/v2/vrp/solve', {
      method: 'POST',
      headers: { 'Authorization': apiKey },
      body: JSON.stringify({ jobs, resources })
    });
    
    const jobId = await response.json();
    
    // Poll for completion
    const solution = await this.pollForSolution(jobId.id);
    
    // Store as baseline schedule
    await this.storeBaselineSchedule(solution);
    
    return solution;
  }
  
  async performRealtimeUpdate(currentState, changes) {
    // Apply current state to jobs
    const jobsWithState = this.applyCurrentState(currentState, changes);
    
    // Use sync solve for rapid response
    const response = await fetch('/v2/vrp/sync/solve', {
      method: 'POST',
      headers: { 'Authorization': apiKey },
      body: JSON.stringify({
        jobs: jobsWithState,
        resources: currentState.resources
      })
    });
    
    const solution = await response.json();
    
    // Deploy immediately to field teams
    await this.deployToField(solution);
    
    return solution;
  }
  
  applyCurrentState(currentState, changes) {
    return currentState.jobs.map(job => ({
      ...job,
      ...changes.jobs?.find(c => c.name === job.name),
      initialResource: job.currentResource,
      initialArrival: job.currentArrival
    }));
  }
}

Performance Optimization

Real-Time Performance Tips:

Minimize Job Count: Only include jobs that could be affected by changes
Use Initial State: Always provide initialResource and initialArrival for existing jobs
Batch Changes: Group multiple changes into single sync solve calls
Cache Results: Store solutions to avoid redundant calculations
Monitor Timing: Track sync solve response times to ensure sub-5-second performance

Error Handling and Resilience

Real-time systems require robust error handling:

Fallback Strategies

Sync Solve Timeout

If sync solve takes too long:

const SYNC_TIMEOUT = 10000; // 10 seconds

async function safeRealtimeUpdate(currentState, changes) {
  try {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), SYNC_TIMEOUT);
    
    const solution = await performRealtimeUpdate(currentState, changes, {
      signal: controller.signal
    });
    
    clearTimeout(timeoutId);
    return solution;
    
  } catch (error) {
    if (error.name === 'AbortError') {
      // Fallback to last known good schedule
      return await getFallbackSchedule(currentState);
    }
    throw error;
  }
}

API Unavailability

When the API is temporarily unavailable:

async function performRealtimeUpdateWithFallback(currentState, changes) {
  try {
    return await performRealtimeUpdate(currentState, changes);
  } catch (error) {
    if (error.status >= 500) {
      // Server error - use local optimization
      return await localFallbackOptimization(currentState, changes);
    }
    throw error;
  }
}

Invalid Solution

When optimization returns an infeasible solution:

function validateSolution(solution, currentState) {
  // Check for unassigned critical jobs
  const criticalUnassigned = solution.unassigned?.filter(job => 
    job.priority > 90 || job.urgency > 90
  );
  
  if (criticalUnassigned?.length > 0) {
    throw new Error(`Critical jobs unassigned: ${criticalUnassigned.map(j => j.name)}`);
  }
  
  return true;
}

Operational Considerations

Update Frequency

Update Frequency Guidelines:

Maximum: 1 update per 30 seconds per resource
Recommended: Batch changes and update every 2-5 minutes
Emergency: Immediate updates for critical changes only

State Management

Track the current schedule state to enable effective real-time updates:

{
  "scheduleVersion": "2024-03-15-v47",
  "lastUpdated": "2024-03-15T10:45:00Z",
  "jobs": [
    {
      "name": "delivery_001",
      "currentResource": "driver_1",
      "currentArrival": "2024-03-15T09:15:00Z",
      "status": "completed"
    },
    {
      "name": "delivery_002", 
      "currentResource": "driver_1",
      "currentArrival": "2024-03-15T11:30:00Z",
      "status": "in_progress"
    },
    {
      "name": "delivery_003",
      "currentResource": "driver_1", 
      "currentArrival": "2024-03-15T13:45:00Z",
      "status": "scheduled"
    }
  ]
}

Monitoring and Analytics

Track key metrics for real-time scheduling performance:

Optimization Speed

Monitor sync solve response times and ensure they stay under 5 seconds

Schedule Stability

Track how often schedules change and the magnitude of disruptions

Customer Impact

Measure appointment changes and customer notification requirements

Resource Utilization

Monitor how real-time changes affect overall resource efficiency

Best Practices

Real-Time Scheduling Best Practices:

Morning Foundation: Always start with comprehensive bulk optimization
State Preservation: Maintain accurate current state with initialResource and initialArrival
Change Batching: Group multiple changes to minimize optimization calls
Error Resilience: Implement fallback strategies for API failures
Performance Monitoring: Track optimization times and schedule stability
Customer Communication: Automate notifications when appointments change
Resource Coordination: Ensure field teams receive updates immediately
Data Integrity: Validate solutions before deployment

Common Use Cases

Emergency Response

Handle urgent service requests that must be inserted into existing schedules with minimal disruption.

Dynamic Demand

Adapt to changing customer demands throughout the day, such as same-day delivery requests or appointment changes.

Resource Management

Respond to driver breaks, vehicle breakdowns, traffic delays, and other resource availability changes.

Service Quality

Maintain optimal routes while respecting customer commitments and service windows.

Sync Solve API

Fast synchronous optimization endpoint

Async Solve API

Comprehensive asynchronous optimization

Job Schemas

Complete job configuration options

Performance Guide

Optimize solving performance

Platform

VRP API

Fill API

Real-Time Scheduling

Real-Time Scheduling

How Real-Time Scheduling Works

Phase 1: Morning Bulk Optimization

Phase 2: Real-Time Adjustments

Key Schema Fields for Real-Time Scheduling

Initial State Fields

Planned State Fields

Real-Time Scheduling Patterns

Pattern 1: New Job Insertion

Pattern 2: Job Cancellation

Pattern 3: Resource Unavailability

Pattern 4: Customer Rescheduling

Implementation Architecture

Backend Integration

Performance Optimization

Error Handling and Resilience

Fallback Strategies

Operational Considerations

Update Frequency

State Management

Monitoring and Analytics

Optimization Speed

Schedule Stability

Customer Impact

Resource Utilization

Best Practices

Common Use Cases

Emergency Response

Dynamic Demand

Resource Management

Service Quality

Sync Solve API

Async Solve API

Job Schemas

Performance Guide

Platform

VRP API

Fill API

Documentation Index

​Real-Time Scheduling

​How Real-Time Scheduling Works

​Phase 1: Morning Bulk Optimization

​Phase 2: Real-Time Adjustments

​Key Schema Fields for Real-Time Scheduling

​Initial State Fields

​Planned State Fields

​Real-Time Scheduling Patterns

​Pattern 1: New Job Insertion

​Pattern 2: Job Cancellation

​Pattern 3: Resource Unavailability

​Pattern 4: Customer Rescheduling

​Implementation Architecture

​Backend Integration

​Performance Optimization

​Error Handling and Resilience

​Fallback Strategies

​Operational Considerations

​Update Frequency

​State Management

​Monitoring and Analytics

Optimization Speed

Schedule Stability

Customer Impact

Resource Utilization

​Best Practices

​Common Use Cases

​Emergency Response

​Dynamic Demand

​Resource Management

​Service Quality

​Related Topics

Sync Solve API

Async Solve API

Job Schemas

Performance Guide

Real-Time Scheduling

How Real-Time Scheduling Works

Phase 1: Morning Bulk Optimization

Phase 2: Real-Time Adjustments

Key Schema Fields for Real-Time Scheduling

Initial State Fields

Planned State Fields

Real-Time Scheduling Patterns

Pattern 1: New Job Insertion

Pattern 2: Job Cancellation

Pattern 3: Resource Unavailability

Pattern 4: Customer Rescheduling

Implementation Architecture

Backend Integration

Performance Optimization

Error Handling and Resilience

Fallback Strategies

Operational Considerations

Update Frequency

State Management

Monitoring and Analytics

Best Practices

Common Use Cases

Emergency Response

Dynamic Demand

Resource Management

Service Quality

Related Topics