Docs
  • Solver
  • Models
    • Field Service Routing
    • Employee Shift Scheduling
  • Platform
Try models
  • Field Service Routing
  • Real-time planning
  • Real-time planning: extended visit

Field Service Routing

    • Introduction
    • Planning AI concepts
    • Metrics and optimization goals
    • Getting started with field service routing
    • Understanding the API
    • Constraints
    • Vehicle resource constraints
      • Shift hours and overtime
      • Lunch breaks and personal appointments
      • Fairness
      • Technician costs
    • Visit service constraints
      • Time windows and opening hours
      • Skills
      • Visit dependencies
      • Visit requirements
      • Multi-vehicle visits
      • Priority visits and optional visits
    • Real-time planning
      • 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
    • Recommendations
      • Recommendations
      • Visit time window recommendations
      • Visit group time window recommendations
    • Time zones and daylight-saving time (DST)
    • New and noteworthy
    • Upgrading to the latest versions
    • Feature requests
    • Reference guide

Real-time planning: extended visit

There are many situations where Real-time planning is necessary.

Sometimes visits take longer than expected.

Consider the following shift schedule:

Carl has three visits scheduled for the day: Visit E, Visit B, and Visit D.

However, Visit E takes much longer than expected.

As a result, Visit B and Visit D need to be rescheduled.

real time planning extended visit

Prerequisites

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

  1. Log in to Timefold Platform: app.timefold.ai

  2. From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.

  3. 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. Batch schedule: extended visit

Carl’s original schedule was generated from the following input dataset during the regular batch scheduling:

  • 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": "Original shift plan: extended visit example"
    }
  },
  "modelInput": {
    "vehicles": [
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl-2027-02-01",
            "startLocation": [33.68786, -84.18487],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z"
          }
        ]
      }
    ],
    "visits": [
      {
        "id": "Visit E",
        "location": [33.84475, -84.63649],
        "serviceDuration": "PT1H"
      },
      {
        "id": "Visit B",
        "location": [33.90719, -84.28149],
        "serviceDuration": "PT1H"
      },
      {
        "id": "Visit D",
        "location":  [33.89351, -84.00649],
        "serviceDuration": "PT1H"
      }
    ]
  }
}
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": "Original shift plan: extended visit example",
    "submitDateTime": "2024-10-25T04:26:15.142743595Z",
    "startDateTime": "2024-10-25T04:26:20.313758011Z",
    "activeDateTime": "2024-10-25T04:26:20.413758011Z",
    "completeDateTime": "2024-10-25T04:31:20.852585436Z",
    "shutdownDateTime": "2024-10-25T04:31:20.952585436Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-174887soft",
    "tags": null,
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "vehicles": [
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "Visit E",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:48:56Z",
                "startServiceTime": "2027-02-01T09:48:56Z",
                "departureTime": "2027-02-01T10:48:56Z",
                "effectiveServiceDuration": "PT1H",
                "travelTimeFromPreviousStandstill": "PT48M56S",
                "travelDistanceMetersFromPreviousStandstill": 54141,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              },
              {
                "id": "Visit B",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T11:29:29Z",
                "startServiceTime": "2027-02-01T11:29:29Z",
                "departureTime": "2027-02-01T12:29:29Z",
                "effectiveServiceDuration": "PT1H",
                "travelTimeFromPreviousStandstill": "PT40M33S",
                "travelDistanceMetersFromPreviousStandstill": 42302,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              },
              {
                "id": "Visit D",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T13:01:19Z",
                "startServiceTime": "2027-02-01T13:01:19Z",
                "departureTime": "2027-02-01T14:01:19Z",
                "effectiveServiceDuration": "PT1H",
                "travelTimeFromPreviousStandstill": "PT31M50S",
                "travelDistanceMetersFromPreviousStandstill": 34289,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT2H39M10S",
              "travelTimeFromStartLocationToFirstVisit": "PT48M56S",
              "travelTimeBetweenVisits": "PT1H12M23S",
              "travelTimeFromLastVisitToEndLocation": "PT37M51S",
              "totalTravelDistanceMeters": 165337,
              "travelDistanceFromStartLocationToFirstVisitMeters": 54141,
              "travelDistanceBetweenVisitsMeters": 76591,
              "travelDistanceFromLastVisitToEndLocationMeters": 34605,
              "endLocationArrivalTime": "2027-02-01T14:39:10Z"
            }
          }
        ]
      }
    ]
  },
  "kpis": {
    "totalTravelTime": "PT2H39M10S",
    "travelTimeFromStartLocationToFirstVisit": "PT48M56S",
    "travelTimeBetweenVisits": "PT1H12M23S",
    "travelTimeFromLastVisitToEndLocation": "PT37M51S",
    "totalTravelDistanceMeters": 165337,
    "travelDistanceFromStartLocationToFirstVisitMeters": 54141,
    "travelDistanceBetweenVisitsMeters": 76591,
    "travelDistanceFromLastVisitToEndLocationMeters": 34605,
    "totalUnassignedVisits": 0
  }
}

modelOutput contains Carl’s shift itinerary.

2. Real-time planning update: extended visit

The plan needs to be updated to reflect the situation in the field.

Visit E took three hours longer than expected.

Update the serviceDuration for Visit E from 1 hour to 4 hours. Add the minStartTravelTime from the most recent planning output dataset (batch or real-time) to each visit.

{
  "visits": [
    {
      "id": "Visit E",
      "location": [33.84475, -84.63649],
      "serviceDuration": "PT4H",
      "minStartTravelTime": "2027-02-01T00:00:00Z"
    },
    {
      "id": "Visit B",
      "location": [33.90719, -84.28149],
      "serviceDuration": "PT1H",
      "minStartTravelTime": "2027-02-01T00:00:00Z"
    },
    {
      "id": "Visit D",
      "location":  [33.89351, -84.00649],
      "serviceDuration": "PT1H",
      "minStartTravelTime": "2027-02-01T00:00:00Z"
    }
  ]
}

Add the itinerary to Carl’s shifts with Visit E, Visit B, and Visit D, including the visit IDs and the visit kind:

{
  "id": "Carl",
  "shifts": [
    {
      "id": "Carl-2027-02-01",
      "startLocation": [33.68786, -84.18487],
      "minStartTime": "2027-02-01T09:00:00Z",
      "maxEndTime": "2027-02-01T17:00:00Z",
      "itinerary": [
        {
          "id": "Visit E",
          "kind": "VISIT"
        },
        {
          "id": "Visit B",
          "kind": "VISIT"
        },
        {
          "id": "Visit D",
          "kind": "VISIT"
        }
      ]
    }
  ]
}

Freeze the departure times for visits that have already occurred and that technicians have begun traveling to by adding freezeDeparturesBeforeTime:

{
  "modelInput": {
    "freezeDeparturesBeforeTime": "2027-02-01T14:10:00Z"
  }
}

Because Carl finished Visit E at 13:48 and is already traveling to Visit B at the freezeDeparturesBeforeTime, this will keep Visit B scheduled after Visit E with a new arrival time.

Submit the updated input dataset to generate the new real-time plan.

  • 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": "Real-time planning: extended visit example"
    }
  },
  "modelInput": {
    "freezeDeparturesBeforeTime": "2027-02-01T14:10:00Z",
    "vehicles": [
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl-2027-02-01",
            "startLocation": [33.68786, -84.18487],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z",
            "itinerary": [
              {
                "id": "Visit E",
                "kind": "VISIT"
              },
              {
                "id": "Visit B",
                "kind": "VISIT"
              },
              {
                "id": "Visit D",
                "kind": "VISIT"
              }
            ]
          }
        ]
      }
    ],
    "visits": [
      {
        "id": "Visit E",
        "location": [33.84475, -84.63649],
        "serviceDuration": "PT4H",
        "minStartTravelTime": "2027-02-01T00:00:00Z"
      },
      {
        "id": "Visit B",
        "location": [33.90719, -84.28149],
        "serviceDuration": "PT1H",
        "minStartTravelTime": "2027-02-01T00:00:00Z"
      },
      {
        "id": "Visit D",
        "location":  [33.89351, -84.00649],
        "serviceDuration": "PT1H",
        "minStartTravelTime": "2027-02-01T00:00:00Z"
      }
    ]
  }
}
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": "Real-time planning: extended visit example",
    "submitDateTime": "2024-10-28T06:44:03.534487996Z",
    "startDateTime": "2024-10-28T06:44:09.323825221Z",
    "activeDateTime": "2024-10-28T06:44:09.423825221Z",
    "completeDateTime": "2024-10-28T06:44:11.087208734Z",
    "shutdownDateTime": "2024-10-28T06:44:11.187208734Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-4medium/-1132701soft",
    "tags": null,
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "vehicles": [
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "Visit E",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:48:56Z",
                "startServiceTime": "2027-02-01T09:48:56Z",
                "departureTime": "2027-02-01T13:48:56Z",
                "effectiveServiceDuration": "PT4H",
                "travelTimeFromPreviousStandstill": "PT48M56S",
                "travelDistanceMetersFromPreviousStandstill": 54141,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              },
              {
                "id": "Visit B",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T14:29:29Z",
                "startServiceTime": "2027-02-01T14:29:29Z",
                "departureTime": "2027-02-01T15:29:29Z",
                "effectiveServiceDuration": "PT1H",
                "travelTimeFromPreviousStandstill": "PT40M33S",
                "travelDistanceMetersFromPreviousStandstill": 42302,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT1H57M18S",
              "travelTimeFromStartLocationToFirstVisit": "PT48M56S",
              "travelTimeBetweenVisits": "PT40M33S",
              "travelTimeFromLastVisitToEndLocation": "PT27M49S",
              "totalTravelDistanceMeters": 125663,
              "travelDistanceFromStartLocationToFirstVisitMeters": 54141,
              "travelDistanceBetweenVisitsMeters": 42302,
              "travelDistanceFromLastVisitToEndLocationMeters": 29220,
              "endLocationArrivalTime": "2027-02-01T15:57:18Z"
            }
          }
        ]
      }
    ]
  },
  "kpis": {
    "totalTravelTime": "PT1H57M18S",
    "travelTimeFromStartLocationToFirstVisit": "PT48M56S",
    "travelTimeBetweenVisits": "PT40M33S",
    "travelTimeFromLastVisitToEndLocation": "PT27M49S",
    "totalTravelDistanceMeters": 125663,
    "travelDistanceFromStartLocationToFirstVisitMeters": 54141,
    "travelDistanceBetweenVisitsMeters": 42302,
    "travelDistanceFromLastVisitToEndLocationMeters": 29220,
    "totalUnassignedVisits": 1
  }
}

modelOutput contains Carl’s updated shift itinerary.

Visit E took much longer than expected, Visit B is scheduled for later in the day, and Visit D must be assigned to another technician or be rescheduled for another day.

See Real-time planning: reassignment for more details.

Next

  • 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.

  • Learn about real-time planning.

  • Real-time planning with pinned visits.

  • Real-time planning and emergency visits.

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