Duration added for first visit on location

In field service routing, technicians often need extra time when visiting a location for the first time in their shift. This overhead can include time to find parking, walk from the vehicle to the property entrance, or set up equipment before starting work.

When a technician visits the same location consecutively (for instance, performing two tasks at the same address), this overhead is only incurred once on the first visit. Subsequent visits at the same location do not need the extra setup time.

1. Use case

A utility company dispatches technicians to perform multiple tasks at apartment buildings. When a technician arrives at a building for the first time, they need to find parking, check in with the building manager, and carry equipment to the correct floor. This overhead typically adds 15 minutes to the first visit. However, if the same technician performs a second task at the same building immediately after, they are already on site and no additional overhead applies.

By configuring durationAddedForFirstVisitOnLocation, the model automatically accounts for this overhead. The solver is also incentivized to schedule multiple visits at the same location consecutively, because doing so avoids the extra overhead on subsequent visits at the same address.

2. How it works

When durationAddedForFirstVisitOnLocation is set, the model checks whether the location of the current visit differs from the location of the previous stop in the technician’s route (either the shift start location or the previous visit’s location).

  • If the technician is arriving at a new location (different from the previous stop), the overhead duration is added to the visit’s effectiveServiceDuration.

  • If the technician is already at the same location (e.g. the previous visit was at the same address), no extra time is added.

The overhead duration is applied per visit, not per location per day. This means that if a technician leaves a location and returns later in the route, the overhead is applied again on the second arrival.

3. Configuration

The durationAddedForFirstVisitOnLocation can be set at two levels:

  • Global default (on RoutePlanConfigOverrides): applies to all visits that do not specify their own value.

  • Per-visit override (on Visit): overrides the global default for a specific visit.

3.1. Setting a global default

To apply the overhead to all visits in the plan, set durationAddedForFirstVisitOnLocation in the model configuration:

{
  "configuration": {
    "modelConfig": {
      "overrides": {
        "durationAddedForFirstVisitOnLocation": "PT15M"
      }
    }
  },
  "modelInput": {
    "visits": [
      {
        "id": "Visit A",
        "location": [33.77301, -84.43838],
        "serviceDuration": "PT1H"
      },
      {
        "id": "Visit B",
        "location": [33.77301, -84.43838],
        "serviceDuration": "PT1H"
      },
      {
        "id": "Visit C",
        "location": [33.78767, -84.43887],
        "serviceDuration": "PT1H"
      }
    ]
  }
}

In this example, Visit A and Visit B are at the same location. If the solver assigns them consecutively to the same technician:

  • Visit A (first arrival at the location): effectiveServiceDuration = 1 hour + 15 minutes = 1 hour 15 minutes.

  • Visit B (already at the same location): effectiveServiceDuration = 1 hour (no overhead added).

  • Visit C (different location): effectiveServiceDuration = 1 hour + 15 minutes = 1 hour 15 minutes.

3.2. Overriding per visit

To use a different overhead duration for a specific visit, or to disable it for a specific visit, set durationAddedForFirstVisitOnLocation directly on the visit:

{
  "modelInput": {
    "visits": [
      {
        "id": "Visit A",
        "location": [33.77301, -84.43838],
        "serviceDuration": "PT1H",
        "durationAddedForFirstVisitOnLocation": "PT30M"
      },
      {
        "id": "Visit B",
        "location": [33.78767, -84.43887],
        "serviceDuration": "PT1H",
        "durationAddedForFirstVisitOnLocation": "PT0M"
      }
    ]
  }
}

  • Visit A uses a 30-minute overhead, regardless of any global default.

  • Visit B has no overhead (explicitly disabled for this visit).

If a visit does not specify durationAddedForFirstVisitOnLocation and no global default is set, no overhead is applied to that visit.

4. Interaction with skill multipliers

The durationAddedForFirstVisitOnLocation duration is added after the skill multiplier is applied to the base serviceDuration. This means the overhead is always added in full, regardless of the technician’s proficiency.

For example, if a technician has a skill multiplier of 2.0 (working at half speed), and a visit has a serviceDuration of 1 hour with durationAddedForFirstVisitOnLocation of 15 minutes:

  • effectiveServiceDuration = (1 hour × 2.0) + 15 minutes = 2 hours 15 minutes.

5. Interaction with visit groups

When visits are part of a visit group, durationAddedForFirstVisitOnLocation is evaluated independently for each technician’s assigned group member. Each technician checks whether their preceding stop was at the same location as the group member they are assigned to.

This means:

  • If both technicians arrive at the location for the first time, both get the overhead.

  • If one technician has a preceding visit at the same location, only the other technician gets the overhead.