Docs
  • Solver
  • Models
    • Field Service Routing
    • Employee Shift Scheduling
    • Pick-up and Delivery Routing
  • Platform
Try models
  • Field Service Routing
  • User guide
  • Output datasets
  • Model output

Field Service Routing

    • Introduction
    • Getting started: Hello world
    • User guide
      • Terminology
      • Use case guide
      • Planning AI concepts
      • Integration
      • Constraints
      • Understanding the API
      • Demo datasets
      • Input datasets
        • Model configuration
        • Model input
        • Planning window
        • Time zones and daylight-saving time (DST)
      • Routing with Timefold’s maps service
      • Input validation
      • Model response
      • Output datasets
        • Metadata
        • Model output
        • Input metrics
        • Key performance indicators (KPIs)
      • Key performance indicators (KPIs)
      • Metrics and optimization goals
    • Vehicle resource constraints
      • Shift hours and overtime
      • Lunch breaks and personal appointments
      • Fairness
      • Route optimization
      • Technician costs
      • Technician ratings
    • Visit service constraints
      • Time windows and opening hours
      • Skills
      • Visit dependencies
      • Multi-vehicle visits
      • Movable visits and multi-day schedules
      • Priority visits and optional visits
      • Visit service level agreement (SLA)
      • Visit requirements, area affinity, and tags
        • Visit requirements
        • Technician coverage area
        • Tags
    • Recommendations
      • Visit time window recommendations
      • Visit group time window recommendations
    • Real-time planning
      • Real-time planning: extended visit
      • Real-time planning: reassignment
      • Real-time planning: emergency visit
      • Real-time planning: no show
      • Real-time planning: technician ill
      • Real-time planning: pinning visits
    • Real-time planning with patches
      • Real-time planning: extended visit (using patches)
      • Real-time planning: reassignment (using patches)
      • Real-time planning: emergency visit (using patches)
      • Real-time planning: no show (using patches)
      • Real-time planning: technician ill (using patches)
      • Real-time planning: pinning visits (using patches)
    • Scenarios
      • Long-running visits
      • Configuring labor law compliance
    • Changelog
    • Upgrade to the latest version
    • Feature requests

Model output

The modelOutput object of the output dataset includes the vehicles and unassignedVisits objects.

unassignedVisits includes the IDs of any visits that could not be assigned during solving:

{
  "modelOutput": {
    "unassignedVisits": [
      "Visit A",
      "Visit B",
      "Visit C"
    ]
  }
}

vehicles includes the vehicles (technicians) that were included in the input dataset and their shifts. shifts includes the shift startTime, the itinerary which includes the visits they have been assigned for that shift, and the metrics for the individual shift which breakdown how the technician will spend their time during the shift.

metrics are also included for the entire vehicle.

In the following dataset, Beth has not been assigned any visits, and Carl has been assigned two visits.

{
  "modelOutput": {
    "vehicles": [
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [],
            "metrics": {
            }
          }
        ],
        "metrics": {
          "activatedShifts": 0,
          "assignedVisits": 0,
          "totalShiftDuration": "PT0S",
          "totalServiceDuration": "PT0S",
          "totalTravelTime": "PT0S",
          "totalTravelDistanceMeters": 0,
          "totalBreakTime": "PT0S",
          "totalWaitingTime": "PT0S",
          "totalOvertime": "PT0S",
          "availableOvertime": "PT0S"
        }
      },
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "Visit B",
                "arrivalTime": "2027-02-01T09:21:36Z",
                "startServiceTime": "2027-02-01T09:21:36Z",
                "departureTime": "2027-02-01T11:21:36Z",
                "effectiveServiceDuration": "PT2H",
                "travelTimeFromPreviousStandstill": "PT21M36S",
                "travelDistanceMetersFromPreviousStandstill": 21412,
                "minStartTravelTime": "2027-02-01T00:00:00Z",
                "kind": "VISIT"
              },
              {
                "id": "Visit A",
                "arrivalTime": "2027-02-01T12:06:14Z",
                "startServiceTime": "2027-02-01T12:06:14Z",
                "departureTime": "2027-02-01T14:06:14Z",
                "effectiveServiceDuration": "PT2H",
                "travelTimeFromPreviousStandstill": "PT44M38S",
                "travelDistanceMetersFromPreviousStandstill": 49808,
                "minStartTravelTime": "2027-02-01T00:00:00Z",
                "kind": "VISIT"
              }
            ],
            "metrics": {
              "totalServiceDuration": "PT4H",
              "totalBreakDuration": "PT0S",
              "totalWaitingTime": "PT0S",
              "totalTravelTime": "PT1H36M4S",
              "travelTimeFromStartLocationToFirstVisit": "PT21M36S",
              "travelTimeBetweenVisits": "PT44M38S",
              "travelTimeFromLastVisitToEndLocation": "PT29M50S",
              "totalTravelDistanceMeters": 105227,
              "travelDistanceFromStartLocationToFirstVisitMeters": 21412,
              "travelDistanceBetweenVisitsMeters": 49808,
              "travelDistanceFromLastVisitToEndLocationMeters": 34007,
              "endLocationArrivalTime": "2027-02-01T14:36:04Z",
              "technicianCosts": 100,
              "overtime": "PT0S",
              "availableOvertime": "PT0S"
            }
          }
        ],
        "metrics": {
          "activatedShifts": 1,
          "assignedVisits": 2,
          "totalShiftDuration": "PT5H36M4S",
          "totalServiceDuration": "PT4H",
          "totalTravelTime": "PT1H36M4S",
          "totalTravelDistanceMeters": 105227,
          "totalBreakTime": "PT0S",
          "totalWaitingTime": "PT0S",
          "totalOvertime": "PT0S",
          "availableOvertime": "PT0S"
        }
      }
    ]
  }
}

Next

  • See the full API spec or try the online API.

  • Learn more about field service routing from our YouTube playlist.

  • Learn about Input metrics.

  • © 2026 Timefold BV
  • Timefold.ai
  • Documentation
  • Changelog
  • Send feedback
  • Privacy
  • Legal
    • Light mode
    • Dark mode
    • System default