{
  "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

Next Steps