Multi-vehicle visits

Some jobs are bigger and more complex than others and require more than a single technician in a single vehicle to be dispatched to complete the work. Visits that require multiple technicians are known as multi-vehicle visits and consist of multiple visits that are part of a visit group.

multi-vehicle visits are visits that occur concurrently, for visits that must be performed in a specific non-concurrent order, see Visit dependencies.

Potential multi-vehicle visit scenarios include:

Assigning multiple technicians to a visit group regardless of their skills, for instance, if equipment needs to be moved from one site to another.
Assigning multiple technicians with the same skill to a visit group, for instance, if a visit group requires two electricians to work together.
Assigning multiple technicians with different skills to a visit group, for instance, when a visit requires an electrician and a plumber and the electrical and plumbing tasks must be completed at the same time.

When scheduling multi-vehicle visits, it’s important to consider factors that may affect the alignment of visits within the visit group and the service duration of the individual visits.

If the visits in a visit group have different service durations technicians need to be available at the right time. If electrical work must be completed for the full duration of the visit and plumbing work is only required for the last part of the visit group, it’s important to align the plumbing visit with the end of the electrical visit.

This guide describes how to schedule multi-vehicle visits, with the following examples:

Multi-vehicle visits
Multi-vehicle visit and skills
Multi-vehicle visit alignment
Multi-vehicle visit with best proficiency

Prerequisites

To run the examples in this guide, you need to authenticate with a valid API key for this model:

Log in to Timefold Platform: app.timefold.ai
From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.
Create a new API key or use an existing one. Ensure the list of models for the API key contains the current model.

In the examples, replace <API_KEY> with the API Key you just copied.

1. Multi-vehicle visit

A multi-vehicle visit occurs when a visit needs multiple technicians (in separate vehicles) to complete the work at the same time.

Multi-vehicle visit are represented by visitGroups which contains multiple visits. In the following example, the visit group contains two visits because two technicians are required to complete the work. Each visit will be assigned to a different technician. The technicians will start and finish their visits at the same time.

{
  "visitGroups": [
    {
      "id": "A",
      "visits": [
        {
          "id": "A1",
          "name": "visit group A 1/2",
          "location": [ 33.80209, -84.40296 ],
          "serviceDuration": "PT2H"
        },
        {
          "id": "A2",
          "name": "visit group A 2/2",
          "location": [ 33.80209, -84.40296 ],
          "serviceDuration": "PT2H"
        }
      ]
    }
  ]
}

In the following example, two technicians in separate vehicles must attend a visit group at the same time. No specific skills have been requested for this visit group.

Ann arrives first at the visit location at 09:26 and waits until Beth arrives at 09:33. When both Ann and Beth are present, they start work.

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans [email protected]

{
  "config": {
    "run": {
      "name": "Multi-vehicle visit example"
    }
  },
  "modelInput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startLocation": [33.68786, -84.18487],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startLocation": [33.70474, -84.06508],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z"
          }
        ]
      }
    ],
    "visitGroups": [
      {
        "id": "A",
        "visits": [
          {
            "id": "A1",
            "name": "visit group A 1/2",
            "location": [ 33.80209, -84.40296 ],
            "serviceDuration": "PT2H"
          },
          {
            "id": "A2",
            "name": "visit group A 2/2",
            "location": [ 33.80209, -84.40296 ],
            "serviceDuration": "PT2H"
          }
        ]
      }
    ]
  }
}

To request the solution, locate the ID from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans/<ID>

{
  "run": {
    "id": "ID",
    "name": "Multi-vehicle visit example",
    "submitDateTime": "2024-12-30T06:44:05.3970981Z",
    "startDateTime": "2024-12-30T06:44:11.640998054Z",
    "activeDateTime": "2024-12-30T06:44:11.953269401Z",
    "completeDateTime": "2024-12-30T06:49:12.003329428Z",
    "shutdownDateTime": "2024-12-30T06:49:12.317456623Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-156207soft",
    "tags": null,
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "A1",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:26:56Z",
                "startServiceTime": "2027-02-01T09:33:56Z",
                "departureTime": "2027-02-01T11:33:56Z",
                "effectiveServiceDuration": "PT2H",
                "travelTimeFromPreviousStandstill": "PT26M56S",
                "travelDistanceMetersFromPreviousStandstill": 29982,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT56M52S",
              "travelTimeFromStartLocationToFirstVisit": "PT26M56S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT29M56S",
              "totalTravelDistanceMeters": 64677,
              "travelDistanceFromStartLocationToFirstVisitMeters": 29982,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 34695,
              "endLocationArrivalTime": "2027-02-01T12:03:52Z"
            }
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "A2",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:33:56Z",
                "startServiceTime": "2027-02-01T09:33:56Z",
                "departureTime": "2027-02-01T11:33:56Z",
                "effectiveServiceDuration": "PT2H",
                "travelTimeFromPreviousStandstill": "PT33M56S",
                "travelDistanceMetersFromPreviousStandstill": 40750,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT1H10M35S",
              "travelTimeFromStartLocationToFirstVisit": "PT33M56S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT36M39S",
              "totalTravelDistanceMeters": 83873,
              "travelDistanceFromStartLocationToFirstVisitMeters": 40750,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 43123,
              "endLocationArrivalTime": "2027-02-01T12:10:35Z"
            }
          }
        ]
      }
    ]
  },
  "kpis": {
    "totalTravelTime": "PT2H7M27S",
    "travelTimeFromStartLocationToFirstVisit": "PT1H52S",
    "travelTimeBetweenVisits": "PT0S",
    "travelTimeFromLastVisitToEndLocation": "PT1H6M35S",
    "totalTravelDistanceMeters": 148550,
    "travelDistanceFromStartLocationToFirstVisitMeters": 70732,
    "travelDistanceBetweenVisitsMeters": 0,
    "travelDistanceFromLastVisitToEndLocationMeters": 77818,
    "totalUnassignedVisits": 0,
    "workingTimeFairnessPercentage": 98.2
  }
}

modelOutput contains Ann’s and Beth’s itineraries.

2. Multi-vehicle visit and skills

In the previous example, no skills were requested for the visit group.

Multi-vehicle visit groups often require technicians with specific skills, for instance, two electricians or one electrician and a plumber.

See the Skills guide to learn about requesting skills for visits and defining technicians' skills.

In the following example, the visit group defines two visits. One visit requires an electrician, and the other visit requires a plumber.

Ann is an electrician and is assigned the visit that requires an electrician. Beth is a plumber and is assigned the visit that requires a plumber.

Ann arrives first at the visit location at 09:26 and waits until Beth arrives at 09:33. When both Ann and Beth are present, they start work.

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans [email protected]

{
  "config": {
    "run": {
      "name": "Multi-vehicle visit with different skills example"
    }
  },
  "modelInput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startLocation": [33.68786, -84.18487],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z",
            "skills": [
              {
                "name": "electrician"
              }
            ]
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startLocation": [33.70474, -84.06508],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z",
            "skills": [
              {
                "name": "plumber"
              }
            ]
          }
        ]
      }
    ],
    "visitGroups": [
      {
        "id": "A",
        "visits": [
          {
            "id": "A1",
            "name": "visit group A 1/2",
            "location": [ 33.80209, -84.40296 ],
            "serviceDuration": "PT2H",
            "requiredSkills": [
              {
                "name": "electrician"
              }
            ]
          },
          {
            "id": "A2",
            "name": "visit group A 2/2",
            "location": [ 33.80209, -84.40296 ],
            "serviceDuration": "PT2H",
            "requiredSkills": [
              {
                "name": "plumber"
              }
            ]
          }
        ]
      }
    ],
    "skills": [
      "electrician",
      "plumber"
    ]
  }
}

To request the solution, locate the ID from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans/<ID>

{
  "run": {
    "id": "ID",
    "name": "Multi-vehicle visit with different skills example",
    "submitDateTime": "2025-01-02T06:28:47.106408637Z",
    "startDateTime": "2025-01-02T06:28:54.059707303Z",
    "activeDateTime": "2025-01-02T06:28:54.359798493Z",
    "completeDateTime": "2025-01-02T06:33:54.439241783Z",
    "shutdownDateTime": "2025-01-02T06:33:54.756471992Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-156207soft",
    "tags": null,
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "A1",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:26:56Z",
                "startServiceTime": "2027-02-01T09:33:56Z",
                "departureTime": "2027-02-01T11:33:56Z",
                "effectiveServiceDuration": "PT2H",
                "travelTimeFromPreviousStandstill": "PT26M56S",
                "travelDistanceMetersFromPreviousStandstill": 29982,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT56M52S",
              "travelTimeFromStartLocationToFirstVisit": "PT26M56S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT29M56S",
              "totalTravelDistanceMeters": 64677,
              "travelDistanceFromStartLocationToFirstVisitMeters": 29982,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 34695,
              "endLocationArrivalTime": "2027-02-01T12:03:52Z"
            }
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "A2",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:33:56Z",
                "startServiceTime": "2027-02-01T09:33:56Z",
                "departureTime": "2027-02-01T11:33:56Z",
                "effectiveServiceDuration": "PT2H",
                "travelTimeFromPreviousStandstill": "PT33M56S",
                "travelDistanceMetersFromPreviousStandstill": 40750,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT1H10M35S",
              "travelTimeFromStartLocationToFirstVisit": "PT33M56S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT36M39S",
              "totalTravelDistanceMeters": 83873,
              "travelDistanceFromStartLocationToFirstVisitMeters": 40750,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 43123,
              "endLocationArrivalTime": "2027-02-01T12:10:35Z"
            }
          }
        ]
      }
    ]
  },
  "kpis": {
    "totalTravelTime": "PT2H7M27S",
    "travelTimeFromStartLocationToFirstVisit": "PT1H52S",
    "travelTimeBetweenVisits": "PT0S",
    "travelTimeFromLastVisitToEndLocation": "PT1H6M35S",
    "totalTravelDistanceMeters": 148550,
    "travelDistanceFromStartLocationToFirstVisitMeters": 70732,
    "travelDistanceBetweenVisitsMeters": 0,
    "travelDistanceFromLastVisitToEndLocationMeters": 77818,
    "totalUnassignedVisits": 0,
    "workingTimeFairnessPercentage": 98.2
  }
}

modelOutput contains Ann’s and Beth’s itineraries.

3. Multi-vehicle visit alignment

Multi-vehicle visit groups can include visits with different durations. For instance, if an electrician is required for the full duration of the visit, but a plumber is only required for part of the visit.

Consider the following visit group with the requirements:

An electrician is required for 2 hours.
A plumber is required for 1 hour.

Visits with different service durations can be aligned at the start of the visit group or at the end of the visit group. By default, visit alignment is set to the start of the visit group.

Alignment is specified in the visitGroup:

{
  "visitGroups": [
    {
      "id": "A",
      "alignment": "END"
    }
  ]
}

In the following example, the visits are aligned with the end of the visit group.

Ann is an electrician and is assigned the visit that requires an electrician. Beth is a plumber and is assigned the visit that requires a plumber.

Ann arrives at the visit location at 09:26 and starts work. Beth arrives at 10:26 and starts work. They both finish at 11:26.

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans [email protected]

{
  "config": {
    "run": {
      "name": "Multi-vehicle visit alignment example"
    }
  },
  "modelInput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startLocation": [33.68786, -84.18487],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z",
            "skills": [
              {
                "name": "electrician"
              }
            ]
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startLocation": [33.70474, -84.06508],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z",
            "skills": [
              {
                "name": "plumber"
              }
            ]
          }
        ]
      }
    ],
    "visitGroups": [
      {
        "id": "A",
        "alignment": "END",
        "visits": [
          {
            "id": "A1",
            "name": "visit group A 1/2",
            "location": [ 33.80209, -84.40296 ],
            "serviceDuration": "PT2H",
            "requiredSkills": [
              {
                "name": "electrician"
              }
            ]
          },
          {
            "id": "A2",
            "name": "visit group A 2/2",
            "location": [ 33.80209, -84.40296 ],
            "serviceDuration": "PT1H",
            "requiredSkills": [
              {
                "name": "plumber"
              }
            ]
          }
        ]
      }
    ],
    "skills": [
      "electrician",
      "plumber"
    ]
  }
}

To request the solution, locate the ID from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans/<ID>

{
  "run": {
    "id": "ID",
    "name": "Multi-vehicle visit alignment example",
    "submitDateTime": "2024-12-30T07:48:24.797190301Z",
    "startDateTime": "2024-12-30T07:48:31.619569451Z",
    "activeDateTime": "2024-12-30T07:48:31.941366977Z",
    "completeDateTime": "2024-12-30T07:53:31.992185593Z",
    "shutdownDateTime": "2024-12-30T07:53:32.345780693Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-156207soft",
    "tags": null,
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "A1",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:26:56Z",
                "startServiceTime": "2027-02-01T09:26:56Z",
                "departureTime": "2027-02-01T11:26:56Z",
                "effectiveServiceDuration": "PT2H",
                "travelTimeFromPreviousStandstill": "PT26M56S",
                "travelDistanceMetersFromPreviousStandstill": 29982,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT56M52S",
              "travelTimeFromStartLocationToFirstVisit": "PT26M56S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT29M56S",
              "totalTravelDistanceMeters": 64677,
              "travelDistanceFromStartLocationToFirstVisitMeters": 29982,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 34695,
              "endLocationArrivalTime": "2027-02-01T11:56:52Z"
            }
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "A2",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:33:56Z",
                "startServiceTime": "2027-02-01T10:26:56Z",
                "departureTime": "2027-02-01T11:26:56Z",
                "effectiveServiceDuration": "PT1H",
                "travelTimeFromPreviousStandstill": "PT33M56S",
                "travelDistanceMetersFromPreviousStandstill": 40750,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT1H10M35S",
              "travelTimeFromStartLocationToFirstVisit": "PT33M56S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT36M39S",
              "totalTravelDistanceMeters": 83873,
              "travelDistanceFromStartLocationToFirstVisitMeters": 40750,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 43123,
              "endLocationArrivalTime": "2027-02-01T12:03:35Z"
            }
          }
        ]
      }
    ]
  },
  "kpis": {
    "totalTravelTime": "PT2H7M27S",
    "travelTimeFromStartLocationToFirstVisit": "PT1H52S",
    "travelTimeBetweenVisits": "PT0S",
    "travelTimeFromLastVisitToEndLocation": "PT1H6M35S",
    "totalTravelDistanceMeters": 148550,
    "travelDistanceFromStartLocationToFirstVisitMeters": 70732,
    "travelDistanceBetweenVisitsMeters": 0,
    "travelDistanceFromLastVisitToEndLocationMeters": 77818,
    "totalUnassignedVisits": 0,
    "workingTimeFairnessPercentage": 98.13
  }
}

modelOutput contains Ann’s and Beth’s itineraries.

4. Multi-vehicle visit with best proficiency

Technicians can have different proficiency levels.

A technician with a proficiency level of 0.5 can complete a 2 hour task in 1 hour, whereas a technician with a proficiency of 1.0 will take the full 2 hours.

See skill multipliers for more details.

When two technicians with the same skill are required for a visit group, you can choose the following service duration strategies:

INDIVIDUAL: the service duration for each visit in the visit group is determined by the proficiency of the technician assigned to the visit.
BEST_PROFICIENCY: the service duration for all visits in the visit group is determined by the technician with the best proficiency.

In the following scenario, a visit group that requires two electricians is assigned to Ann and Beth. Both visits in the visit group have a service duration of 2 hours. Ann has a proficiency of 0.5, and Beth has a proficiency of 1.0.

Using the INDIVIDUAL service duration strategy, Ann’s visit will have a service duration of 1 hour, and Beth’s visit will have a service duration of 2 hours.

Using the BEST_PROFICIENCY service duration strategy, both visits will have a service duration of 1 hour.

ServiceDurationStrategy only applies to technicians with the same skills.

Technician’s proficiency in a skill is set by adding the multiplier to the skill:

{
  "id": "Ann",
  "shifts": [
    {
      "id": "Ann-2027-02-01",
      "startLocation": [33.68786, -84.18487],
      "minStartTime": "2027-02-01T09:00:00Z",
      "maxEndTime": "2027-02-01T17:00:00Z",
      "skills": [
        {
          "name": "electrician",
          "multiplier": 0.5
        }
      ]
    }
  ]
}

The service duration strategy for a visit group is set by adding either INDIDIVUAL or BEST_PROFICIENCY to serviceDurationStrategy:

{
  "visitGroups": [
    {
      "id": "A",
      "serviceDurationStrategy": "BEST_PROFICIENCY"
    }
  ]
}

In the following example, a visit group requires two electricians. Each visit in the visit group has a service duration of 2 hours.

Ann and Beth are assigned the visits. The service duration strategy is BEST_PROFICIENCY and the service duration will be determined by the most proficient technician.

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans [email protected]

{
  "config": {
    "run": {
      "name": "Multi-vehicle visit best proficiency"
    }
  },
  "modelInput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startLocation": [33.68786, -84.18487],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z",
            "skills": [
              {
                "name": "electrician",
                "multiplier": 0.5
              }
            ]
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startLocation": [33.70474, -84.06508],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z",
            "skills": [
              {
                "name": "electrician",
                "multiplier": 1.0
              }
            ]
          }
        ]
      }
    ],
    "visitGroups": [
      {
        "id": "A",
        "serviceDurationStrategy": "BEST_PROFICIENCY",
        "visits": [
          {
            "id": "A1",
            "name": "visit group A 1/2",
            "location": [ 33.80209, -84.40296 ],
            "serviceDuration": "PT2H",
            "requiredSkills": [
              {
                "name": "electrician"
              }
            ]
          },
          {
            "id": "A2",
            "name": "visit group A 2/2",
            "location": [ 33.80209, -84.40296 ],
            "serviceDuration": "PT2H",
            "requiredSkills": [
              {
                "name": "electrician"
              }
            ]
          }
        ]
      }
    ],
    "skills": [ "electrician" ]
  }
}

To request the solution, locate the ID from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans/<ID>

{
  "run": {
    "id": "ID",
    "name": "Multi-vehicle visit best proficiency",
    "submitDateTime": "2025-01-02T06:55:02.249544617Z",
    "startDateTime": "2025-01-02T06:55:09.049699532Z",
    "activeDateTime": "2025-01-02T06:55:09.369711741Z",
    "completeDateTime": "2025-01-02T07:00:09.432180923Z",
    "shutdownDateTime": "2025-01-02T07:00:09.704172749Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-156207soft",
    "tags": null,
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "A1",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:26:56Z",
                "startServiceTime": "2027-02-01T09:33:56Z",
                "departureTime": "2027-02-01T10:33:56Z",
                "effectiveServiceDuration": "PT1H",
                "travelTimeFromPreviousStandstill": "PT26M56S",
                "travelDistanceMetersFromPreviousStandstill": 29982,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT56M52S",
              "travelTimeFromStartLocationToFirstVisit": "PT26M56S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT29M56S",
              "totalTravelDistanceMeters": 64677,
              "travelDistanceFromStartLocationToFirstVisitMeters": 29982,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 34695,
              "endLocationArrivalTime": "2027-02-01T11:03:52Z"
            }
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "A2",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:33:56Z",
                "startServiceTime": "2027-02-01T09:33:56Z",
                "departureTime": "2027-02-01T10:33:56Z",
                "effectiveServiceDuration": "PT1H",
                "travelTimeFromPreviousStandstill": "PT33M56S",
                "travelDistanceMetersFromPreviousStandstill": 40750,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT1H10M35S",
              "travelTimeFromStartLocationToFirstVisit": "PT33M56S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT36M39S",
              "totalTravelDistanceMeters": 83873,
              "travelDistanceFromStartLocationToFirstVisitMeters": 40750,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 43123,
              "endLocationArrivalTime": "2027-02-01T11:10:35Z"
            }
          }
        ]
      }
    ]
  },
  "kpis": {
    "totalTravelTime": "PT2H7M27S",
    "travelTimeFromStartLocationToFirstVisit": "PT1H52S",
    "travelTimeBetweenVisits": "PT0S",
    "travelTimeFromLastVisitToEndLocation": "PT1H6M35S",
    "totalTravelDistanceMeters": 148550,
    "travelDistanceFromStartLocationToFirstVisitMeters": 70732,
    "travelDistanceBetweenVisitsMeters": 0,
    "travelDistanceFromLastVisitToEndLocationMeters": 77818,
    "totalUnassignedVisits": 0,
    "workingTimeFairnessPercentage": 97.36
  }
}

modelOutput contains contains Ann’s and Beth’s itineraries with both visits in Visit Group A’s serviceDuration set to 1 hour.

Understand the constraints of the Field Service Routing model.
See the full API spec or try the online API.
Manage shift times with Time zones and daylight-saving time (DST) changes.
Use Time windows to specify visit availability and limit when visits can be scheduled.
Learn about Visit requirements and Visit dependencies.

Multi-vehicle visits

Prerequisites

1. Multi-vehicle visit

2. Multi-vehicle visit and skills

3. Multi-vehicle visit alignment

4. Multi-vehicle visit with best proficiency

Next