Getting started with field service routing

This guide introduces Timefold’s Field Service Routing model and walks you through the steps to use Timefold Platform to create an optimized field service routing itinerary.

The steps in this guide can be completed in under 10 minutes.

1. Field service routing hello world example

This hello world uses an example with one vehicle and one visit to demonstrate the process of requesting and retrieving a solution from Timefold’s field service routing model.

In the example, Ann works as a technician for a telecom company and drives between locations to connect people’s homes to the internet.

1.1. Prerequisites

To follow this guide, you need:

An active Timefold Platform account
An API client (optional but recommended)

1.2. Start a trial

To register for a trial with Timefold Platform:

Navigate to https://app.timefold.ai.
Click Log in.
Click Sign up.

Either enter the email address and password you want to register with and click continue or select one of the federated log-in options and follow the prompts.
Verify your email address.

A tenant will be created for you and you can invite other users to your tenant.

Complete a field service routing test run.

From the Models page, select Field Service Routing.
Click + New run.
Select Basic and click Run.

When the test run begins you will see the Overview page which shows the constraints score changing over the length of the model run.

Click Visualizations to view visualizations of the solution.

1.2.1. Route Map

The route map includes the routes for each vehicle with the vehicles' start locations and each visit:

1.2.2. By vehicle

The vehicle visualization shows the itinerary for each vehicle:

1.2.3. By Visit

The visit visualization breaks down the itinerary for each visit:

1.3. Creating a dataset

A dataset for the Field Service Routing model must include information about your customers' requests and your technicians' availability. For instance, customers who require an internet connection at their homes, and service technicians who can visit those customers and install the necessary equipment.

Requests can also include when customers are available to let the technician in and the required skills necessary to complete the visit. Requirements for the technician are also included, for instance, required breaks, how many technicians are required to complete the work, and the skill level of the technicians, to name a few.

You create your dataset using our predefined model schema which follows the OpenAPI specification.

See API Spec for more information.

The modelInput object contains the dataset to be optimized, which, at a minimum, must include vehicles and visits:

{
  "modelInput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startLocation": [33.68786, -84.18487],
            "minStartTime": "2027-02-01T09:00:00Z"
          }
        ]
      }
    ],
    "visits": [
      {
        "id": "Visit A",
        "location": [33.77301, -84.43838],
        "serviceDuration": "PT1H30M"
      }
    ]
  }
}

Copy this example dataset into a file called sample.json to use in this hello world example.

1.3.1. Vehicles

In this example, there is one vehicle. vehicles includes id and shifts.

{
  "vehicles": [
    {
      "id": "Ann",
      "shifts": [
        {
          "id": "Ann-2027-02-01",
          "startLocation": [33.68786, -84.18487],
          "minStartTime": "2027-02-01T09:00:00Z"
        }
      ]
    }
  ]
}

id identifies the vehicle. In this case, the id has the value "Ann" to identify this as Ann’s vehicle.

shifts represents a period of time the vehicle and its crew is working, typically a day shift. For example, 1-Feb from 09:00 to 17:00. shifts includes an id, startLocation, and minStartTime.

id identifies one shift (one day) worked in this vehicle. Ann works this shift, and the string "Ann-2027-02-01" identifies this specific shift.

startLocation provides Ann’s location at the start of the shift. This is the location she travels from when she leaves for the first visit.

minStartTime sets the earliest time Ann can start her shift.

1.3.2. Visits

In this example, there is one customer who requires an internet connection at their home. The visits object includes information about the customer’s location:

{
  "visits": [
    {
      "id": "Visit A",
      "location": [33.77301, -84.43838],
      "serviceDuration": "PT1H30M"
    }
  ]
}

id identifies the visit. In this case, id has the value "Visit A", but you could use a customer identifier from your CRM or another meaningful identifier.

location provides the location of the visit. This is the customer’s home that needs a connection to the internet.

serviceDuration is the estimated duration of the visit. serviceDuration uses the ISO 8601 duration format. The value "PT1H30M" indicates the estimated duration is 1 hour and 30 minutes.

1.4. Post the dataset

You have two options to post the dataset.

Post the dataset in the Timefold Platform UI
Post the dataset to the Timefold OpenAPI

1.4.1. Post the dataset in the Timefold Platform UI

Typically, you post the dataset to the API. However, for testing purposes, you can upload your sample.json directly in the Timefold Platform UI.

Log into the Timefold Platform dashboard: https://app.timefold.ai
Select the Field Service Routing tile.
Click New run.
Select Custom and click Next
Upload the sample.json file you saved earlier.
Click Schedule run.
Navigate to the Output section to see the completed route

1.4.2. Post the dataset to the Timefold OpenAPI

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.

Request the solution for your dataset by posting the sample.json file to the API endpoint /v1/route-plans/.

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]

1.5. Output from the request

The output to the API request follows:

{
  "id": "ID",
  "name": "NAME",
  "submitDateTime": "2024-07-05T07:27:28.178351918Z",
  "startDateTime": null,
  "activeDateTime": null,
  "completeDateTime": null,
  "shutdownDateTime": null,
  "solverStatus": "SOLVING_SCHEDULED",
  "score": null,
  "tags": null,
  "validationResult": null
}

The output includes an ID and NAME that have been assigned to identify the run associated with the dataset. You’ll use this ID to retrieve the results. Later, you’ll use NAME to locate more information in Timefold Platform.

solverStatus confirms the dataset has been scheduled for solving.

1.6. Request the solution

Append the <ID> from the output you received to the API endpoint /v1/route-plans/ and create a GET request to retrieve the solution:

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

1.6.1. Completed route

{
  "run": {
    "id": "ID",
    "name": "NAME",
    "submitDateTime": "2024-07-05T07:27:28.178351918Z",
    "startDateTime": "2024-07-05T07:27:32.349292848Z",
    "activeDateTime": "2024-07-05T07:27:32.359292848Z",
    "completeDateTime": "2024-07-05T07:27:34.435404549Z",
    "shutdownDateTime": "2024-07-05T07:27:34.535404549Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-3569soft",
    "tags": null,
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "Visit A",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:29:57Z",
                "startServiceTime": "2027-02-01T09:29:57Z",
                "departureTime": "2027-02-01T10:59:57Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT29M57S",
                "travelDistanceMetersFromPreviousStandstill": 31492,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT59M29S",
              "travelTimeFromStartLocationToFirstVisit": "PT29M57S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT29M32S",
              "totalTravelDistanceMeters": 65476,
              "travelDistanceFromStartLocationToFirstVisitMeters": 31492,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 33984,
              "endLocationArrivalTime": "2027-02-01T11:29:29Z"
            }
          }
        ]
      }
    ]
  },
  "kpis": {
    "totalTravelTime": "PT59M29S",
    "travelTimeFromStartLocationToFirstVisit": "PT29M57S",
    "travelTimeBetweenVisits": "PT0S",
    "travelTimeFromLastVisitToEndLocation": "PT29M32S",
    "totalTravelDistanceMeters": 65476,
    "travelDistanceFromStartLocationToFirstVisitMeters": 31492,
    "travelDistanceBetweenVisitsMeters": 0,
    "travelDistanceFromLastVisitToEndLocationMeters": 33984,
    "totalUnassignedVisits": 0
  }
}

The output shows the solverStatus is SOLVING COMPLETED.

modelOutput contains the solution for the dataset.

{
  "itinerary": [
    {
      "id": "Visit A",
      "kind": "VISIT",
      "arrivalTime": "2027-02-01T09:29:57Z",
      "startServiceTime": "2027-02-01T09:29:57Z",
      "departureTime": "2027-02-01T10:59:57Z",
      "effectiveServiceDuration": "PT1H30M",
      "travelTimeFromPreviousStandstill": "PT29M57S",
      "travelDistanceMetersFromPreviousStandstill": 31492,
      "minStartTravelTime": "2027-02-01T00:00:00Z"
    }
  ]
}

itinerary includes the details for Ann’s schedule, including when she arrives at the customer’s location to connect their home to the internet.

arrivalTime at the visit and startServiceTime are both 2027-02-01T09:29:57Z, or 9:29 on February 1, 2027. The effectiveServiceDuration is 1 hour and 30 minutes ("PT1H30M"), and the departureTime is 2027-02-01T10:59:57Z or 10:59.

Ann’s schedule for her shift is below. Travel time is marked in orange on the timeline, and Visit A is marked in green.

Field Service Routing time view

Beyond hello world

This example walked you through creating a simple dataset to create a schedule for one vehicle to travel to one visit. Timefold optimizes routes for thousands of technicians automatically and incorporates constraints for skill requirements, shift limits, and more.

Configure a webhook

In this getting started guide, you learned how to retrieve the solution for your dataset through the API and Timefold Platform. However, you can configure a webhook to receive the solution without the need to poll Timefold’s API.

To configure a webhook:

Log in to Timefold Platform app.timefold.ai
From the Dashboard, click the tenant menu drop-down menu and select Tenant settings.
Select Webhook and click New webhook.
Give your webhook a name.
Enter the URL for your webhook and the header values.
Enable the webhook and click Add webhook.

See Configuring webhooks for more information.

Try the demo dataset

Timefold platform includes a demo dataset you can use to explore the functionality of the platform.

Access the demo dataset in the UI

To access the demo dataset in the UI:

Log into Timefold Platform: app.timefold.ai
Select the Field Service Routing tile.
Click New Run.
Select the demo dataset you would like to run from the drop-down menu, and click Schedule run.

Access the demo dataset with the API

To get the list of available demo datasets from the API, make the following call:

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

To download the BASIC demo dataset, make the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/demo-data/BASIC -o sample.json

To post the demo dataset, use the following API call:

The output from the POST operation includes a run ID that you need for subsequent commands.

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

To get the current status and score of the dataset, replace <ID> with the identifier from the previous post operation and make 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

To get the complete route plan, replace <ID> with the identifier from the previous post operation and make 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>

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 Shift hours and overtime.

Getting started with field service routing

1. Field service routing hello world example

1.1. Prerequisites

1.2. Start a trial

1.2.1. Route Map

1.2.2. By vehicle

1.2.3. By Visit

1.3. Creating a dataset

1.3.1. Vehicles

1.3.2. Visits

1.4. Post the dataset

1.4.1. Post the dataset in the Timefold Platform UI

1.4.2. Post the dataset to the Timefold OpenAPI

1.5. Output from the request

1.6. Request the solution

1.6.1. Completed route

Beyond hello world

Configure a webhook

Try the demo dataset

Access the demo dataset in the UI

Access the demo dataset with the API

Next