{
  "resources": [
    {
      "name": "technician-1",
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z",
          "start": {
            "name": "Office",
            "latitude": 40.7128,
            "longitude": -74.0060
          },
          "end": {
            "name": "Office",
            "latitude": 40.7128,
            "longitude": -74.0060
          },
          "breaks": [
            {
              "type": "WINDOWED",
              "from": "2024-03-15T12:00:00Z",
              "to": "2024-03-15T13:00:00Z",
              "duration": 2700
            }
          ]
        }
      ],
      "tags": ["plumbing", "electrical", "hvac"]
    },
    {
      "name": "technician-2",
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z",
          "start": {
            "name": "Office",
            "latitude": 40.7128,
            "longitude": -74.0060
          },
          "end": {
            "name": "Office",
            "latitude": 40.7128,
            "longitude": -74.0060
          },
          "breaks": [
            {
              "type": "WINDOWED",
              "from": "2024-03-15T12:00:00Z",
              "to": "2024-03-15T13:00:00Z",
              "duration": 2700
            }
          ]
        }
      ],
      "tags": ["plumbing", "appliance"]
    }
  ],
  "jobs": [
    {
      "name": "appointment-1",
      "location": {
        "name": "Mrs. Johnson - Water heater",
        "latitude": 40.7260,
        "longitude": -73.9897
      },
      "duration": 5400,
      "windows": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T10:00:00Z",
          "hard": true
        }
      ],
      "tags": [{"name": "plumbing", "hard": true}],
      "priority": 100
    },
    {
      "name": "appointment-2",
      "location": {
        "name": "Mr. Smith - AC maintenance",
        "latitude": 40.7489,
        "longitude": -73.9680
      },
      "duration": 3600,
      "windows": [
        {
          "from": "2024-03-15T09:00:00Z",
          "to": "2024-03-15T12:00:00Z",
          "hard": true
        }
      ],
      "tags": [{"name": "hvac", "hard": true}],
      "priority": 80
    },
    {
      "name": "appointment-3",
      "location": {
        "name": "Ms. Davis - Electrical outlet",
        "latitude": 40.7614,
        "longitude": -73.9776
      },
      "duration": 1800,
      "windows": [
        {
          "from": "2024-03-15T10:00:00Z",
          "to": "2024-03-15T14:00:00Z",
          "hard": false,
          "weight": 50
        }
      ],
      "tags": [{"name": "electrical", "hard": true}],
      "priority": 60
    },
    {
      "name": "appointment-4",
      "location": {
        "name": "Mr. Brown - Dishwasher repair",
        "latitude": 40.7074,
        "longitude": -74.0113
      },
      "duration": 2700,
      "windows": [
        {
          "from": "2024-03-15T13:00:00Z",
          "to": "2024-03-15T16:00:00Z",
          "hard": true
        }
      ],
      "tags": [{"name": "appliance", "hard": true}],
      "priority": 90
    },
    {
      "name": "appointment-5",
      "location": {
        "name": "Mrs. Wilson - Pipe leak",
        "latitude": 40.7356,
        "longitude": -73.9925
      },
      "duration": 3600,
      "windows": [
        {
          "from": "2024-03-15T14:00:00Z",
          "to": "2024-03-15T17:00:00Z",
          "hard": true
        }
      ],
      "tags": [{"name": "plumbing", "hard": true}],
      "priority": 95,
      "urgency": 100
    },
    {
      "name": "appointment-6",
      "location": {
        "name": "Mr. Garcia - Thermostat install",
        "latitude": 40.7195,
        "longitude": -74.0089
      },
      "duration": 2400,
      "windows": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T12:00:00Z",
          "hard": false,
          "weight": 30
        },
        {
          "from": "2024-03-15T14:00:00Z",
          "to": "2024-03-15T17:00:00Z",
          "hard": false,
          "weight": 70
        }
      ],
      "tags": [{"name": "hvac", "hard": true}],
      "priority": 50
    },
    {
      "name": "appointment-7",
      "location": {
        "name": "Ms. Taylor - Garbage disposal",
        "latitude": 40.7527,
        "longitude": -73.9772
      },
      "duration": 1800,
      "windows": [
        {
          "from": "2024-03-15T09:00:00Z",
          "to": "2024-03-15T17:00:00Z",
          "hard": true
        }
      ],
      "tags": [{"name": "plumbing", "hard": true}],
      "priority": 40
    },
    {
      "name": "appointment-8",
      "location": {
        "name": "Mr. Lee - Circuit breaker",
        "latitude": 40.7438,
        "longitude": -73.9916
      },
      "duration": 4800,
      "windows": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T11:00:00Z",
          "hard": true
        }
      ],
      "tags": [{"name": "electrical", "hard": true}],
      "priority": 85
    }
  ],
  "options": {
    "snapUnit": 900,
    "partialPlanning": false,
    "weights": {
      "waitTimeWeight": 50,
      "urgencyWeight": 100
    }
  }
}

{
  "solution": {
    "routes": [
      {
        "resource": "technician-1",
        "jobs": [
          {
            "job": "appointment-1",
            "arrival": "2024-03-15T08:00:00Z",
            "departure": "2024-03-15T09:30:00Z",
            "service": "Mrs. Johnson - Water heater"
          },
          {
            "job": "appointment-8",
            "arrival": "2024-03-15T09:45:00Z",
            "departure": "2024-03-15T11:05:00Z",
            "service": "Mr. Lee - Circuit breaker"
          },
          {
            "job": "appointment-2",
            "arrival": "2024-03-15T11:15:00Z",
            "departure": "2024-03-15T12:15:00Z",
            "service": "Mr. Smith - AC maintenance"
          },
          {
            "job": "appointment-3",
            "arrival": "2024-03-15T13:30:00Z",
            "departure": "2024-03-15T14:00:00Z",
            "service": "Ms. Davis - Electrical outlet"
          },
          {
            "job": "appointment-6",
            "arrival": "2024-03-15T14:15:00Z",
            "departure": "2024-03-15T14:55:00Z",
            "service": "Mr. Garcia - Thermostat install"
          }
        ],
        "summary": {
          "totalJobs": 5,
          "totalServiceTime": 13500,
          "totalTravelTime": 4200,
          "totalWorkTime": 17700
        }
      },
      {
        "resource": "technician-2",
        "jobs": [
          {
            "job": "appointment-7",
            "arrival": "2024-03-15T09:00:00Z",
            "departure": "2024-03-15T09:30:00Z",
            "service": "Ms. Taylor - Garbage disposal"
          },
          {
            "job": "appointment-4",
            "arrival": "2024-03-15T13:15:00Z",
            "departure": "2024-03-15T14:00:00Z",
            "service": "Mr. Brown - Dishwasher repair"
          },
          {
            "job": "appointment-5",
            "arrival": "2024-03-15T14:15:00Z",
            "departure": "2024-03-15T15:15:00Z",
            "service": "Mrs. Wilson - Pipe leak"
          }
        ],
        "summary": {
          "totalJobs": 3,
          "totalServiceTime": 7500,
          "totalTravelTime": 2400,
          "totalWorkTime": 9900
        }
      }
    ],
    "metrics": {
      "onTimeAppointments": 8,
      "totalAppointments": 8,
      "averageWaitTime": 0,
      "skillMatchRate": 1.0
    }
  }
}

​
Service Appointments

This example shows how to schedule home service appointments where customers have specific time windows and each service requires different durations. This is perfect for field service, repairs, installations, or any business with appointment-based operations.

​
Business Scenario

A home services company needs to schedule technicians for:
  • 8 service appointments throughout the day
  • Customers with specific morning/afternoon preferences
  • Varying service durations (30 min to 2 hours)
  • 2 technicians with different skills
  • Minimize customer wait times

​
Complete Request

{
  "resources": [
    {
      "name": "technician-1",
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z",
          "start": {
            "name": "Office",
            "latitude": 40.7128,
            "longitude": -74.0060
          },
          "end": {
            "name": "Office",
            "latitude": 40.7128,
            "longitude": -74.0060
          },
          "breaks": [
            {
              "type": "WINDOWED",
              "from": "2024-03-15T12:00:00Z",
              "to": "2024-03-15T13:00:00Z",
              "duration": 2700
            }
          ]
        }
      ],
      "tags": ["plumbing", "electrical", "hvac"]
    },
    {
      "name": "technician-2",
      "shifts": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T17:00:00Z",
          "start": {
            "name": "Office",
            "latitude": 40.7128,
            "longitude": -74.0060
          },
          "end": {
            "name": "Office",
            "latitude": 40.7128,
            "longitude": -74.0060
          },
          "breaks": [
            {
              "type": "WINDOWED",
              "from": "2024-03-15T12:00:00Z",
              "to": "2024-03-15T13:00:00Z",
              "duration": 2700
            }
          ]
        }
      ],
      "tags": ["plumbing", "appliance"]
    }
  ],
  "jobs": [
    {
      "name": "appointment-1",
      "location": {
        "name": "Mrs. Johnson - Water heater",
        "latitude": 40.7260,
        "longitude": -73.9897
      },
      "duration": 5400,
      "windows": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T10:00:00Z",
          "hard": true
        }
      ],
      "tags": [{"name": "plumbing", "hard": true}],
      "priority": 100
    },
    {
      "name": "appointment-2",
      "location": {
        "name": "Mr. Smith - AC maintenance",
        "latitude": 40.7489,
        "longitude": -73.9680
      },
      "duration": 3600,
      "windows": [
        {
          "from": "2024-03-15T09:00:00Z",
          "to": "2024-03-15T12:00:00Z",
          "hard": true
        }
      ],
      "tags": [{"name": "hvac", "hard": true}],
      "priority": 80
    },
    {
      "name": "appointment-3",
      "location": {
        "name": "Ms. Davis - Electrical outlet",
        "latitude": 40.7614,
        "longitude": -73.9776
      },
      "duration": 1800,
      "windows": [
        {
          "from": "2024-03-15T10:00:00Z",
          "to": "2024-03-15T14:00:00Z",
          "hard": false,
          "weight": 50
        }
      ],
      "tags": [{"name": "electrical", "hard": true}],
      "priority": 60
    },
    {
      "name": "appointment-4",
      "location": {
        "name": "Mr. Brown - Dishwasher repair",
        "latitude": 40.7074,
        "longitude": -74.0113
      },
      "duration": 2700,
      "windows": [
        {
          "from": "2024-03-15T13:00:00Z",
          "to": "2024-03-15T16:00:00Z",
          "hard": true
        }
      ],
      "tags": [{"name": "appliance", "hard": true}],
      "priority": 90
    },
    {
      "name": "appointment-5",
      "location": {
        "name": "Mrs. Wilson - Pipe leak",
        "latitude": 40.7356,
        "longitude": -73.9925
      },
      "duration": 3600,
      "windows": [
        {
          "from": "2024-03-15T14:00:00Z",
          "to": "2024-03-15T17:00:00Z",
          "hard": true
        }
      ],
      "tags": [{"name": "plumbing", "hard": true}],
      "priority": 95,
      "urgency": 100
    },
    {
      "name": "appointment-6",
      "location": {
        "name": "Mr. Garcia - Thermostat install",
        "latitude": 40.7195,
        "longitude": -74.0089
      },
      "duration": 2400,
      "windows": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T12:00:00Z",
          "hard": false,
          "weight": 30
        },
        {
          "from": "2024-03-15T14:00:00Z",
          "to": "2024-03-15T17:00:00Z",
          "hard": false,
          "weight": 70
        }
      ],
      "tags": [{"name": "hvac", "hard": true}],
      "priority": 50
    },
    {
      "name": "appointment-7",
      "location": {
        "name": "Ms. Taylor - Garbage disposal",
        "latitude": 40.7527,
        "longitude": -73.9772
      },
      "duration": 1800,
      "windows": [
        {
          "from": "2024-03-15T09:00:00Z",
          "to": "2024-03-15T17:00:00Z",
          "hard": true
        }
      ],
      "tags": [{"name": "plumbing", "hard": true}],
      "priority": 40
    },
    {
      "name": "appointment-8",
      "location": {
        "name": "Mr. Lee - Circuit breaker",
        "latitude": 40.7438,
        "longitude": -73.9916
      },
      "duration": 4800,
      "windows": [
        {
          "from": "2024-03-15T08:00:00Z",
          "to": "2024-03-15T11:00:00Z",
          "hard": true
        }
      ],
      "tags": [{"name": "electrical", "hard": true}],
      "priority": 85
    }
  ],
  "options": {
    "snapUnit": 900,
    "partialPlanning": false,
    "weights": {
      "waitTimeWeight": 50,
      "urgencyWeight": 100
    }
  }
}

​
Key Configuration Choices

​
Time Windows

{
  "windows": [{
    "from": "2024-03-15T08:00:00Z",
    "to": "2024-03-15T10:00:00Z",
    "hard": true
  }]
}
Must arrive within this window or job cannot be scheduled.

​
Service Durations

Jobs have varying durations based on complexity:
  • Quick fixes: 30 minutes (outlet repair, disposal)
  • Standard service: 45-60 minutes (AC maintenance, dishwasher)
  • Major repairs: 90-120 minutes (water heater, circuit breaker)

​
Skill Matching

Technicians have different skills:
  • Technician 1: plumbing, electrical, hvac (multi-skilled)
  • Technician 2: plumbing, appliance (specialized)
Jobs require specific skills via hard tags.

​
Time Snapping

"options": {
  "snapUnit": 900  // 15 minutes
}
Arrivals are rounded to 15-minute intervals:
  • 8:07 → 8:15
  • 8:15 → 8:15
  • 8:23 → 8:30
This creates cleaner schedules and sets realistic customer expectations.

​
Expected Response

{
  "solution": {
    "routes": [
      {
        "resource": "technician-1",
        "jobs": [
          {
            "job": "appointment-1",
            "arrival": "2024-03-15T08:00:00Z",
            "departure": "2024-03-15T09:30:00Z",
            "service": "Mrs. Johnson - Water heater"
          },
          {
            "job": "appointment-8",
            "arrival": "2024-03-15T09:45:00Z",
            "departure": "2024-03-15T11:05:00Z",
            "service": "Mr. Lee - Circuit breaker"
          },
          {
            "job": "appointment-2",
            "arrival": "2024-03-15T11:15:00Z",
            "departure": "2024-03-15T12:15:00Z",
            "service": "Mr. Smith - AC maintenance"
          },
          {
            "job": "appointment-3",
            "arrival": "2024-03-15T13:30:00Z",
            "departure": "2024-03-15T14:00:00Z",
            "service": "Ms. Davis - Electrical outlet"
          },
          {
            "job": "appointment-6",
            "arrival": "2024-03-15T14:15:00Z",
            "departure": "2024-03-15T14:55:00Z",
            "service": "Mr. Garcia - Thermostat install"
          }
        ],
        "summary": {
          "totalJobs": 5,
          "totalServiceTime": 13500,
          "totalTravelTime": 4200,
          "totalWorkTime": 17700
        }
      },
      {
        "resource": "technician-2",
        "jobs": [
          {
            "job": "appointment-7",
            "arrival": "2024-03-15T09:00:00Z",
            "departure": "2024-03-15T09:30:00Z",
            "service": "Ms. Taylor - Garbage disposal"
          },
          {
            "job": "appointment-4",
            "arrival": "2024-03-15T13:15:00Z",
            "departure": "2024-03-15T14:00:00Z",
            "service": "Mr. Brown - Dishwasher repair"
          },
          {
            "job": "appointment-5",
            "arrival": "2024-03-15T14:15:00Z",
            "departure": "2024-03-15T15:15:00Z",
            "service": "Mrs. Wilson - Pipe leak"
          }
        ],
        "summary": {
          "totalJobs": 3,
          "totalServiceTime": 7500,
          "totalTravelTime": 2400,
          "totalWorkTime": 9900
        }
      }
    ],
    "metrics": {
      "onTimeAppointments": 8,
      "totalAppointments": 8,
      "averageWaitTime": 0,
      "skillMatchRate": 1.0
    }
  }
}

​
Schedule Timeline

​
Understanding the Results

​
Time Window Compliance

All hard time windows met:
  • Morning appointments (8-10 AM): ✓ Scheduled first
  • Urgent afternoon repair: ✓ Prioritized at 14:15
  • Flexible windows: ✓ Optimally scheduled

​
Skill Utilization

The solver correctly matched skills:
  • HVAC jobs → Technician 1 (has HVAC skills)
  • Appliance repair → Technician 2 (has appliance skills)
  • Plumbing/Electrical → Distributed based on availability

​
Workload Balance

  • Technician 1: 5 appointments
  • Technician 2: 3 appointments
The imbalance is due to:
  • Skill requirements
  • Longer service durations for Tech 1’s jobs

​
Customer Experience

Optimized for customer satisfaction:
  1. All appointments within requested windows
  2. 15-minute arrival slots for clear communication
  3. High-priority/urgent jobs scheduled appropriately
  4. Minimal travel between nearby appointments

​
Advanced Features

​
Handling No-Shows

Add padding for potential delays: 
{
  "jobs": [{
    "name": "appointment-1",
    "duration": 5400,
    "padding": 600  // 10-minute buffer
  }]
}

​
Preferred Technicians

Use soft tags for customer preferences: 
{
  "jobs": [{
    "tags": [
      {"name": "plumbing", "hard": true},
      {"name": "prefers-tech-1", "hard": false}
    ]
  }]
}

​
Emergency Appointments

High urgency for same-day additions: 
{
  "priority": 100,
  "urgency": 100,
  "windows": [{
    "from": "2024-03-15T14:00:00Z",
    "to": "2024-03-15T17:00:00Z",
    "hard": true
  }]
}

​
Try It Yourself

1

Prepare Your Data

Create a JSON file with your service appointments, including:
  • Customer locations
  • Time preferences
  • Service durations
  • Required skills
2

Configure Resources

Set up your technicians with:
  • Working hours and breaks
  • Skill tags
  • Start/end locations
3

Submit Request

curl -X POST 'https://api.solvice.io/v2/vrp/solve' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d @service-appointments.json
4

Process Results

Parse the solution to:
  • Generate technician schedules
  • Send customer notifications
  • Update your scheduling system

​
Best Practices

  • Use hard windows only when absolutely necessary
  • Offer multiple time slots when possible
  • Consider travel time when setting windows
  • Build in buffer time for complex jobs
  • Use hard tags for required skills
  • Cross-train technicians for flexibility
  • Track skill utilization rates
  • Plan training based on demand
  • Send confirmations with 15-minute arrival windows
  • Update customers if running late
  • Collect feedback on time preferences
  • Track on-time performance

​
Next Steps

Break Management

Configure complex break schedules

Recurring Services

Plan regular maintenance visits

Emergency Dispatch

Handle urgent same-day requests

Territory Planning

Optimize technician territories