Timefold Field Service Routing User Guide

Table of Contents
timefold logo

1. Introduction

Field service routing optimizes itineraries of employees visiting customers locations over the upcoming period of time. Visits require the employees to have various skills and to arrive in the specified availability windows. The goal is to minimize the time employees spend by traveling and waiting, and, by that, increasing the number of scheduled visits.

Field Service Routing map view

2. Terms

Term Description

Planning window

The period of time for which we plan ahead; e.g. the next two weeks or the next month.

Visit

A visit to a customer’s location associated with providing a service.

Visit availability window

A time period in which an employee has to arrive and finish the service.

Non-movable visit

A visit with its availability window within a single day.

Movable visit

A visit with its availability window spanning over multiple days. If its due time is outside the planning window, the visit may be left unassigned.

Vehicle

Represents an employee or a group of employees sharing the same vehicle

Vehicle shift

A work day for the vehicle crew defined by a start time and by various end times.

3. REST API

3.1. Create problem data set

Create problem data set using predefined model schema that follows OpenAPI specification. The application provides several out-of-the-box examples that can be used as a starting point.

Example 1. List sample data sets REST API endpoint call

GET /v1/demo-data

Example 2. Get sample data set REST API endpoint call

GET /v1/demo-data/{dataset_name}

3.2. Submit a data set

Submit the unsolved data set using the REST API. The application validates the input and returns a unique identifier of the problem. The solving process is scheduled and eventually starts.

Example 3. Submit problem data set REST API endpoint call

POST /v1/route-plans

3.2.1. Get current best solution and check status

Check the current best solution and receive information about the solving process. The solution contains the optimized route plan. Use id attribute returned by submit a data set step.

Example 4. Check status REST API endpoint call

GET /v1/route-plans/{id}

3.3. Terminate solving

Terminate the solving process and receive the current best solution. Use id attribute returned by submit a data set step.

Example 5. Terminate solving REST API endpoint call

DELETE /v1/route-plans/{id}

3.4. Get all solving processes

Get info about the status of all solving processes.

Example 6. Terminate solving REST API endpoint call

GET /v1/route-plans

4. Data model

This section describes the Field Service Routing data model.

4.1. Route plan

The route plan is the top-level object of the Field Service Routing API. It serves both as an input and output of the API.

It is a container for all the data necessary for optimizing the route plan, as the table below summarizes.

Id Required Format Description

name

false

string

A label identifying the route plan.

planningWindow

true

object

The planning window is a time interval to schedule for.

constraintConfiguration

false

object

The constraint configuration contains global parameters of constraints.

vehicles

true

array

An array of all vehicles.

vehicleShifts

true

array

An array of all vehicle shifts.

visits

true

array

An array of all visits that should be scheduled.

visitGroups

false

array

An array of all visit groups that should be scheduled. A visit group defines a multi-resource visit, i.e. a visit that needs to be serviced by multiple vehicle shifts at the same time.

tags

false

array

An array of all tags to match by a vehicle shift with a visit.

freezeDeparturesBeforeTime

false

string (ISO-8601 date and time)

The date and time before which all vehicle shifts are considered pinned ("frozen").

In other words, every visit assigned to a vehicle shift which the shift already completed or started travelling to before the freezeDeparturesBeforeTime is considered pinned and will not be reassigned to another shift or moved to a different position in the list of assigned visits for the shift.

Usable for real-time planning scenario, such as re-submitting a plan that contains already assigned visits which must be pinned, such as in the following scenario:

1. The plan A is submitted to the solver, the solution for A contains assigned visits to shifts.

2. A few hours later, the solution for A is used as a base for an updated plan B adding new visits to be assigned after a (user-chosen) time T.

3. The plan B contains visits already planned (assigned during A's planning) to a time before T that need to be preserved, since they already happened.

4. When the plan B is submitted for solving, it needs to have the freezeDeparturesBeforeTime set to T.

When omitted, no pinning/freeze is in effect.

The Field Service Routing adds the following attributes in the reply.

Id Format Description Example

status

object

The current status of the route plan

See route plan status

totalTravelTime

string (ISO-8601 duration)

The total travel time by all the vehicle shifts.

"PT2H15M"

totalUnassignedVisits

number

The total amount of visits that were not assigned in the route plan.

10

4.1.1. Route plan status

The route plan status object is used to give more information about the solver run.

Id Format Description Example

id

string

Unique identifier of the solver run

"3e26e4d5-9447-46c5-8c3b-a8fef78bc1cb"

name

string

Name of the solver run

"VehicleRoutePlan-2023-11-29T09:09:30.825044+01:00"

submitDateTime

string (ISO-8601 date, time and time zone offset)

The date the route plan was submitted to solve.

"2023-11-29T09:09:30.825044+01:00"

solverStatus

string (one of: "NOT_SOLVING", "SOLVING_SCHEDULED", "SOLVING_ACTIVE", "SOLVING_COMPLETED", "SOLVING_FAILED", "SOLVING_DISABLED")

The status of the solver.

"SOLVING_COMPLETED"

score

string

The current score of the route plan, as calculated by the solver.

"0hard/-7medium/-8116soft"

4.2. Constraint configuration

The constraint configuration contains weights of soft constraint and additional constraint parameters, influencing whether these constraints trigger and how much they impact the solution’s score.

Id Format Description Example

endLocationMaxArrivalTimeSoftLimitWeight

number

A weight of the End location max arrival time soft limit constraint.

1

lastVisitMaxDepartureTimeSoftLimitWeight

number

A weight of the Last visit max departure time soft limit constraint.

1

minimizeTravelTimeWeight

number

A weight of the Minimize travel time constraint.

1

minimizeTravelDistanceWeight

number

A weight of the Minimize travel distance constraint.

0

preferVisitsScheduledToEarliestDayWeight

number

A weight of the Prefer visits scheduled to the earliest day constraint.

1

preferSchedulingOptionalVisitsWeight

number

A weight of the Prefer scheduling optional visits constraint.

1

minimizeVisitCompletionRiskWeight

number

A weight of the Minimize the visit completion risk constraint.

1

visitCompletionRiskMinimalTimeToShiftEnd

string (ISO-8601 duration)

A length of the time window between the visit departure time and the vehicle shift end. If a visit ends in this time window, its completion is considered risky.

"PT1H"

visitCompletionRiskMinimalPriority

string

A minimal priority of a visit to consider it for the risk evaluation.

"LOW"

4.3. Planning window

The planning windows specified a time range to plan for.

Id Required Format Description Example

startDate

true

string (ISO-8601 date and time)

A start date of the planning window.

"2023-11-27T00:00:00"

endDate

true

string (ISO-8601 date and time)

An end date of the planning window.

"2023-11-30T23:59:59"

4.4. Vehicle

The vehicle represents a single vehicle visiting customers across the planning window.

Id Required Format Description Example

id

true

string

A unique string identifier of the vehicle.

"Alice Fox"

vehicleType

true

string

A type of the vehicle

"VAN"

4.5. Vehicle shift

Vehicle shift is an instance of a vehicle projected to a time interval in which the vehicle operates. In a multi-day field service routing, a vehicle shift a typically a single working day of the vehicle crew. After the optimization process, each vehicle shift contains an ordered list of visits.

Id Required Format Description Example

id

true

string

A unique string identifier of the vehicle shift.

"vehicle-shift-8026f548"

vehicle

true

string

A unique string identifier of the associated vehicle.

"Alice Fox"

shiftStartTime

true

string (ISO-8601 date and time)

A start date and time of the vehicle shift.

"2023-11-27T09:00:00"

shiftStartsFrom

false

string

Specifies if the shift starts from its start location or from the first visit.

"SHIFT_START_LOCATION" (default) or "FIRST_VISIT"

lastVisitMaxDepartureTimeSoftLimit

false

string (ISO-8601 date and time)

A maximal departure time from the last visit (soft).

"2023-11-27T17:00:00"

lastVisitMaxDepartureTimeHardLimit

false

string (ISO-8601 date and time)

A maximal departure time from the last visit (hard).

"2023-11-27T17:15:00"

endLocationMaxArrivalTimeSoftLimit

false

string (ISO-8601 date and time)

A maximal arrival time to the end location (soft).

"2023-11-27T17:00:00"

endLocationMaxArrivalTimeHardLimit

false

string (ISO-8601 date and time)

A maximal arrival time to the end location (hard).

"2023-11-27T17:15:00"

maxTravelTimePerVisitHardLimit

false

string (ISO-8601 duration)

A maximal travel time limit per visit (hard).

"PT1H"

startLocation

true

array (latitude, longitude)

A start location coordinates of the vehicle shift.

[ 52.5441475, -0.265105009 ]

endLocation

true

array (latitude, longitude)

An end location coordinates of the vehicle shift.

[ 52.5441475, -0.265105009 ]

tags

false

array

An array of tag references.

["plumber", "emergency"]

serviceDurationMultipliers

false

array

Multipliers affecting a visit service duration.

[ { "tag": "plumber", "multiplier": 0.8 } ]

temporaryTagSets

false

array

Tags that are applicable within specified time intervals.

[ { "start": "2023-11-27T09:00:00", "end": "2023-11-27T13:00:00", "tags": [ "plumber" ] }

floatingBreaks

false

array

An array of floating breaks.

[{ "id": "233", "triggerTime": "2023-11-27T12:00:00", "duration": "PT1H" } ]

unavailabilities

false

array

An array of unavailabilities.

[{ "id": "123", "startTime": "2023-11-27T14:00:00", "endTime": "2023-11-27T16:00:00" } ]

movableOccupationRatioThreshold

false

number

Influences the ratio between movable and non-movable visits to assigned to this vehicle shift.

"0.5"

The Field Service Routing adds the following attributes in the reply.

Id Format Description Example

visits

array

An array of visit references in the order of the vehicle’s itinerary.

["974a7e67", "75b436f"]

statistics

object

Statistics of the vehicle shift route.

4.6. Vehicle shift statistics

Id Format Description Example

totalTravelTime

string (ISO-8601 duration)

The total travel time by the vehicle shift.

"PT2H15M"

travelTimeFromStartLocationToFirstVisit

string (ISO-8601 duration)

The travel time from the start location to the first visit.

"PT10M"

travelTimeBetweenVisits

string (ISO-8601 duration)

The total travel time between visits excluding the travel time from the start location to the first visit and the travel time from the last visit to the end location.

"PT2H"

travelTimeFromLastVisitToEndLocation

string (ISO-8601 duration)

The travel time from the last visit to the end location.

"PT5M"

totalTravelDistanceMeters

integer

The total travel distance by the vehicle shift in meters.

25000

travelDistanceFromStartLocationToFirstVisitMeters

integer

The travel distance from the start location to the first visit in meters.

3000

travelDistanceBetweenVisitsMeters

integer

The total travel distance in meters between visits excluding the distances from the start location to the first visit and from the last visit to the end location.

20000

travelDistanceFromLastVisitToEndLocationMeters

integer

The travel distance from the last visit to the end location in meters.

2000

endLocationArrivalTime

string (ISO-8601 date and time)

The arrival time of the vehicle shift at the endLocation.

"2023-11-27T17:15:00"

4.7. Visit

A visit represents an individual service job at customer location. For every visit, you can define the following attributes.

Id Required Format Description Example

id

true

string

A unique string identifier of the visit.

"974a7e67"

name

true

string

A name of the visit.

"Alex Pot"

location

true

array (latitude, longitude)

A location coordinates of the visit.

[ 52.0233688, 0.239470348 ],

minimumStartTime

true

string (ISO-8601 date and time)

A minimum start time of the visit

"2023-11-27T10:00:00"

maximumStartTime

true

string (ISO-8601 date and time)

A maximum start of the visit

"2023-11-27T10:00:00"

maximumEndTime

true

string (ISO-8601 date and time)

A maximum end of the visit

"2023-11-27T14:00:00"

serviceDuration

true

string (ISO-8601 duration)

The estimated duration of the service.

"PT15M"

serviceDurationAdjustment

false

string (ISO-8601 duration)

The adjustment of the serviceDuration. Can be negative.

"PT15M"

requiredTags

false

array

An array of tag references required by this visit.

["plumber", "emergency"]

priority

false

string

Visit priority.

"HIGH"

visitDependencies

false

array

An array of visit dependencies.

[ { "id": "1", "precedingVisit": "58f18bb7", "minDelay": "PT2H" } ]

pinningRequested

false

boolean

Determines if the user requested to pin this particular visit (the visit must already be assigned).

Setting pinningRequested == true on a visit forces this visit pinned even when the departure to this visit happens after the Route Plan freezeDeparturesBeforeTime (so it is not considered pinned by default). Please note that all previous visits in the vehicle shift assigned to this visit must be pinned, otherwise an exception is thrown.

Useful when pinning needs to be extended beyond freezeDeparturesBeforeTime only for a particular visit or visits.

true, false (default)

minimumStartTravelTime

false

string (ISO-8601 date and time)

The minimum time when a shift can start travelling to this visit. When set, it can postpone visit’s arrivalTime.

Important: The value is set automatically during solving, the user must only preserve the value when re-submitting a plan that contains already assigned pinned visits.

For example, consider the following scenario:

1. The plan A is submitted to the solver, the solution for A contains assigned visits to shifts, including visits' minimumStartTravelTime.

2. A few hours later, the solution for A is used as a base for an updated plan B adding new visits to be assigned after a (user-chosen) time T.

3. The plan B contains visits already planned (assigned during A's planning) to a time before T that need to be preserved, since they already happened.

4. When the plan B is submitted for solving with the freezeDeparturesBeforeTime set to T, the model will: a. use the existing minimumStartTravelTime values of pinned visits to calculate their arrivalTime correctly, b.calculate minimumStartTravelTime values for the unpinned visits to ensure they are assigned into the time period after the freezeDeparturesBeforeTime.

"2023-11-27T14:00:00"

Apart from the attributes above, that serve as an input for the optimization, the Field Service Routing adds the following attributes in the reply.

Id Format Description Example

vehicleShift

string

A reference to a vehicle shift assigned to this visit.

"vehicle-shift-8026f548"

arrivalTime

string (ISO-8601 date and time)

The arrival time of the vehicle at the customer location.

"2023-11-27T11:10:09"

startServiceTime

string (ISO-8601 date and time)

The beginning of the service at the customer location.

"2023-11-27T11:10:09"

departureTime

string (ISO-8601 date and time)

The end of the service at the customer location.

"2023-11-27T11:25:09"

effectiveServiceDuration

string (ISO-8601 duration)

The effective duration of the service after applying the serviceDurationMultipliers of the assigned vehicle shift and adding the serviceDurationAdjustment.

"PT15M"

travelTimeFromPreviousStandstill

string (ISO-8601 duration)

The travel time either from the previous visit or from the start location of the assigned vehicle shift.

"PT10M3S"

travelDistanceMetersFromPreviousStandstill

integer

The travel distance either from the previous visit or from the start location of the assigned vehicle shift.

5000

breakDuration

string (ISO-8601 duration)

The duration of all breaks the assigned vehicle shift is eligible to take between the previous visit and this visit.

"PT30M"

4.8. Visit Group

A visit group represents a multi-resource visit, i.e. a group of individual service jobs that need to be performed at customer location at the same time. For every visit group, you can define the following attributes.

Id Required Format Description Example

id

true

string

A unique string identifier of the visit group.

"974a7e67"

serviceDurationStrategy

false

string

The strategy to calculate the service duration of the visits in this visit group:

INDIVIDUAL: The service duration of each visit in the group is calculated independently based on the service proficiency modifiers for the assigned vehicle shift. When multiple service proficiency modifiers match the visit’s requirements, their average is used to adjust the service duration. (default)

BEST_PROFICIENCY: The service duration of each visit in the group is calculated using the best service proficiency modifiers (separately for each tag) from all vehicle shifts assigned to the visits in the visit group. When multiple service proficiency modifiers match the requirements of a visit in the group, their average is used to adjust the visit’s service duration.

"INDIVIDUAL" (default), "BEST_PROFICIENCY"

visits

false

array

An array of visits that form together the visit group.

[ {"id":"1abcd","name":"John","location":[49.288087,16.562172],"minimumStartTime":"2024-02-23T08:00:00","maximumEndTime":"2024-02-23T12:00:00","serviceDuration":"PT1H","priority":"NORMAL"} ],

4.9. Tag

Tags connect visits with the right vehicle shift. For instance, a visit may require a plumber skill, which limits the range of vehicle shifts that can pick up the visit.

Id Required Format Description Example

name

true

string

A unique string identifier of the tag.

"plumber"

4.10. Visit dependency

A visit can declare a dependency on some other visit, specifying a minimal delay between them. For example, a technological break between two maintenance tasks.

Id Required Format Description Example

id

true

string

A unique string identifier of the visit dependency.

"25"

precedingVisit

true

string

A reference to the preceding visit that must be completed first.

"58f18bb7"

4.11. Floating break

Represents a break a vehicle shift is eligible for that is scheduled to the first available interval between two visits after the triggerTime. The arrival time to the visit after the scheduled break is delayed accordingly.

Id Required Format Description Example

id

true

string

A unique string identifier of the floating break.

"353"

triggerTime

true

string (ISO-8601 date and time)

The earliest time to schedule the break at.

"2023-11-27T12:00:00"

4.12. Unavailability

Represents a time interval in which the vehicle shift is unavailable and thus, it cannot work on any visit or travel to the next location. The travel to the next location starts only after the unavailability, as the location of the vehicle during the unavailability is unknown.

Id Required Format Description Example

id

true

string

A unique string identifier of the unavailability.

"123"

startTime

true

string (ISO-8601 date and time)

The unavailability start time.

"2023-11-27T14:00:00"

endTime

true

string (ISO-8601 date and time)

The unavailability end time.

"2023-11-27T16:00:00"

location

false

array (latitude, longitude)

The location coordinates of the unavailability

[ 52.0233688, 0.239470348 ],

5. Constraints

5.1. Hard

Hard constraints represent rules and limitations of the real world that the resulting solution has to respect. For that reason, the Field Service Model prefers leaving visits unassigned to breaking hard constraints.

5.1.1. Vehicle shift end time (hard)

A vehicle shift may end either by:

The former is more appropriate for vehicles that end their shifts in employer’s depot or office. The latter is suitable for vehicle shifts that end at employee’s home and the travel from the last visit home is considered outside the working hours.

Make sure to define at least one of these hard limits, otherwise the vehicle shift effectively never ends.

5.1.2. Require tags

Both vehicle shifts and visits define tags. You can use tags to model skills, regions, contractors, and similar. The constraint makes sure visits are assigned to vehicle shifts that match their required tags. Triggers for any visit assigned to a vehicle shift with at least a single missing tag required by the visit.

A vehicle shift can also define temporary tags that apply only in the specified time interval.

5.1.3. Require service maximum start time

Vehicles have to fulfill the service within the customer visit’s availability window. The constraint triggers when the vehicle shift’s start service time exceeds the visit’s maximum start time.

5.1.4. Require service maximum end time

Vehicles have to fulfill the service within the customer visit’s availability window. The constraint triggers when the vehicle shift’s departure time exceeds the visit’s maximum end time.

5.1.5. Maximum travel time per visit hard limit

Vehicle shift can define a maximum travel time spent per a single visit. This limit may result in visits in distant locations being unassigned. The constraint triggers when the vehicle shift’s travel time exceeds the limit.

5.1.6. Require visit dependency delay

Visits may depend on each other with a minimal required delay between them. For instance, between two consecutive maintenance tasks, there needs to be a technological pause. Triggers if a visit starts before the minimal delay after the departure time from the defined preceding visit.

5.1.7. Floating breaks

Apply a defined break at the first opportunity; e.g. assign a lunch break before the nearest visit after 12 a.m. Represents a break a vehicle shift is eligible for that is scheduled to the first available interval between two visits after the triggerTime. The arrival time to the visit after the scheduled break is delayed accordingly.

5.1.8. Balance movable and non-movable visits

Often it is important to spread movable visits over the planning windows to keep free time for optimizing non-movable visits and placing sudden emergencies.

The movable occupation ratio threshold defines the capacity for movable visits in the following way:

If the vehicle shift occupancy grows above the threshold, the constraint penalizes the solution score for the exceeding travel and service duration of movable visits assigned to this vehicle shift.

5.2. Soft

Soft constraints represent optimization goals and additional requirements on the quality of feasible solutions.

5.2.1. Vehicle shift end time (soft)

Similarly to Vehicle shift end time (hard), there are also soft limits of the vehicle shift end:

If you use these soft limits, make sure to set them to earlier time than the corresponding hard limits.

5.2.2. Minimize travel time

Minimizes the total travel time over all vehicles. Triggers for every visit assigned to a vehicle shift. This constraint represents an optimization goal to reduce the travel time and is typically not used in combination with the Minimize travel distance constraint.

5.2.3. Minimize travel distance

Minimizes the total travel distance over all vehicles. Triggers for every visit assigned to a vehicle shift. This constraint represents an optimization goal to reduce the travel distance and, by that, also the mileage driven together with a fuel consumption. It is typically not used in combination with the Minimize travel time constraint.

5.2.4. Prefer visits scheduled to the earliest day

Schedules movable visits to the earliest possible day to reduce the risk of not being able to assign them later. The constraint triggers for every movable visit that is scheduled to a later date that its minimum start time.

5.2.5. Prefer scheduling optional visits

Assigns as many optional visits as possible without breaking hard constraints and without making a mandatory visit unassigned. Optional visits with approaching deadlines come first. Applies to any unassigned optional visit with its maximum end time outside the current planning window.

5.2.6. Minimize the visit completion risk

If a vehicle crew gets behind the schedule during the day, there is a risk the last one or two visits might not get finished. As a result, these visits have to be rescheduled to some other day.

This constraint penalizes any visit with its departure time exceeding the visitCompletionRiskMinimalTimeToShiftEnd based on the visit priority. To define the minimal priority level to consider for the risk evaluation, use the visitCompletionRiskMinimalPriority.

That way, high-priority visits are more likely to be scheduled earlier in the day, while low-priority visits are likely to move towards the vehicle shift end.

5.3. Constraint configuration

Constraint configuration contains weights of soft constraints together with additional constraint parameters. Every constraint defines a match weight; a basic score impact for every constraint match. The overall score impact of a constraint match is calculated by multiplying the match weight by the constraint weight.

The default value of a constraint weight is 1. To make the score impact of a constraint ten times bigger, set the related constraint weight to 10. To effectively turn a constraint off, set the related constraint weight to 0.

6. Migration guide

6.1. From 0.10.0 to 0.11.0

The version 0.11.0 introduces changes to the API. The changes are not backward compatible and require changes to the client code.

6.1.1. Visits belonging to a visit group moved under VehicleRoutePlan.visitGroups

Affects the following REST endpoints:

  • GET /v1/route-plans/{id}

  • DELETE /v1/route-plans/{id}

  • POST /v1/route-plans/{id}/recommendations/recommend-time-windows

The visits which are members of a visit group have been moved from VehicleRoutePlan.visits under individual visit groups at VehicleRoutePlan.visitGroups. Other (non-multi-resource) visits remain at VehicleRoutePlan.visits.

Before:

{
  "visits": [
    {"id":"1","name":"A single-resource visit","location":[33.67749834423416,-84.32354038529364],"minimumStartTime":"2024-02-23T08:00:00","maximumEndTime":"2024-02-23T18:00:00","serviceDuration":"PT1H30M","requiredTags":["electrician","north"],"priority":"NORMAL", ...},
    {"id":"2a","name":"Ivy Fox (1/2)","location":[33.67749834423416,-84.32354038529364],"minimumStartTime":"2024-02-23T08:00:00","maximumEndTime":"2024-02-23T18:00:00","serviceDuration":"PT1H30M","requiredTags":["electrician","north"],"priority":"NORMAL", "visitGroup": "VG Ivy Fox 1", ...},
    {"id":"2b","name":"Ivy Fox (2/2)","location":[33.67749834423416,-84.32354038529364],"minimumStartTime":"2024-02-23T08:00:00","maximumEndTime":"2024-02-23T18:00:00","serviceDuration":"PT1H","requiredTags":["electrician","north"],"priority":"NORMAL", "visitGroup": "VG Ivy Fox 1", ...},
    ...
  ],
  ...
}

After:

{
  "visits": [
    {"id":"1","name":"A single-resource visit","location":[33.67749834423416,-84.32354038529364],"minimumStartTime":"2024-02-23T08:00:00","maximumEndTime":"2024-02-23T18:00:00","serviceDuration":"PT1H30M","requiredTags":["electrician","north"],"priority":"NORMAL", ...},
    ...
  ],
  "visitGroups": [
    {"id":"VG Ivy Fox 1",
     "serviceDurationStrategy": "INDIVIDUAL",
     "visits": [
            {"id":"2a","name":"Ivy Fox (1/2)","location":[33.67749834423416,-84.32354038529364],"minimumStartTime":"2024-02-23T08:00:00","maximumEndTime":"2024-02-23T18:00:00","serviceDuration":"PT1H30M","requiredTags":["electrician","north"],"priority":"NORMAL", ...},
            {"id":"2b","name":"Ivy Fox (2/2)","location":[33.67749834423416,-84.32354038529364],"minimumStartTime":"2024-02-23T08:00:00","maximumEndTime":"2024-02-23T18:00:00","serviceDuration":"PT1H","requiredTags":["electrician","north"],"priority":"NORMAL", ...}
        ]
    }
    ...
  ],
  ...
}

6.2. From 0.9.0 to 0.10.0

The version 0.10.0 introduces changes to the API. The changes are not backward compatible and require changes to the client code.

6.2.1. totalDrivingTime changes to totalTravelTime

Affects the following REST endpoints:

  • GET /v1/route-plans/{id}

  • DELETE /v1/route-plans/{id}

  • POST /v1/route-plans/{id}/recommendations/recommend-time-windows

Before:

{
  "totalDrivingTime": "PT1H",
  ...
}

After:

{
  "totalTravelTime": "PT1H",
  ...
}

6.2.2. VehicleShift startDateTime changes to shiftStartTime

Affects the following REST endpoints:

  • GET /v1/route-plans/{id}

  • POST /v1/route-plans

  • DELETE /v1/route-plans/{id}

  • POST /v1/route-plans/{id}/recommendations/recommend-time-windows

Before:

"vehicleShifts": [
  {
    "startDateTime": "2019-01-01T00:00:00",
    ...
  }
]

After:

"vehicleShifts": [
  {
    "shiftStartTime": "2019-01-01T00:00:00",
    ...
  }
]

6.2.3. VehicleShift totalDrivingTime and endLocationArrivalTime change to statistics.totalTravelTime and statistics.endLocationArrivalTime

Affects the following REST endpoints:

  • GET /v1/route-plans/{id}

  • DELETE /v1/route-plans/{id}

  • POST /v1/route-plans/{id}/recommendations/recommend-time-windows

Before:

"vehicleShifts": [
  {
    "totalDrivingTime": "PT1H",
    "endLocationArrivalTime": "2019-01-01T00:00:00",
    ...
  }
]

After:

"vehicleShifts": [
  {
    "statistics": {
      "totalTravelTime": "PT1H",
      "endLocationArrivalTime": "2019-01-01T00:00:00",
      ...
    }
  }
]

6.2.4. Visit drivingTimeFromPreviousStandstill changes to travelTimeFromPreviousStandstill

Affects the following REST endpoints:

  • GET /v1/route-plans/{id}

  • DELETE /v1/route-plans/{id}

  • POST /v1/route-plans/{id}/recommendations/recommend-time-windows

Before:

"visits": [
  {
    "drivingTimeFromPreviousStandstill": "PT1H",
    ...
  }
]

After:

"visits": [
  {
    "travelTimeFromPreviousStandstill": "PT1H",
    ...
  }
]

6.3. Recommend Time Windows

Use this feature to react to abrupt changes in daily operations. Consider a call center that handles incoming service requests. The customer provides the operator with time windows when the service can take place. The Recommend Time Windows API allows you to validate if the service can take place in one of the windows provided by the customer, in a quick way. The API provides a list of vehicle shift recommendations for every time window specified. The vehicle shift recommendations are sorted by quality, with the best fit first.

Example 7. Get time window recommendations for a new visit

POST /v1/route-plans/{id}/recommendations/recommend-time-windows

6.3.1. Recommend Time Windows API input

Description of Recommend Time Windows API input.

Name Required Format Description Example

maxNumberOfRecommendationsPerTimeWindow

true

int

Upper limit for a number of vehicle shifts to recommend for a new visit, per each time window.

"maxNumberOfRecommendationsPerTimeWindow": 3

fitVisitId

true

string

Identifier of the visit to get the time window recommendations for. The visit with given identifier needs to be a part of the routePlan.

"fitVisitId": "plumber-ann"

timeWindows

true

array

Time windows to get the vehicle shift recommendations for.

`"timeWindows": [ { "startTime":"2024-01-23T08:00:00", "endTime":"2024-01-23T18:00:00" }, { "startTime":"2024-01-24T08:00:00", "endTime":"2024-01-24T12:00:00" } ] `

routePlan

true

array

Input route plan that contains visit with identifier specified by fitVisitId attribute.

`"routePlan": { "name": "ATLANTA_SMALL", "vehicles": [ { "id": "1", "vehicleType": "VAN" }, …​ `

6.3.2. Recommend Time Windows API output

Description of Recommend Time Windows API output.

Name Format Description Example

scoreDiff

string

Total score difference between the new solution with the fitted visit and the solution without the fitted visit.

"scoreDiff": "0hard/48000medium/-480soft"

constraintDiffs

array

Per-constraint score difference between the new solution with the fitted visit and the solution without the fitted visit.

`"constraintDiffs": [ { "score": "0hard/0medium/-386soft", "constraintName": "Minimize travel time" }, …​ `

timeWindow

object

Time window that the recommendation ties to.

"timeWindow": { "startTime": "2024-01-23T08:00:00", "endTime": "2024-01-23T18:00:00" }

vehicleShift

object

Vehicle shift recommendation for the time window and the visit to fit.

"vehicleShift": { "id": "14", "statistics": { "totalTravelTime": "PT1H37M46S", "totalTravelDistanceMeters": 63324, "endLocationArrivalTime": "2024-01-23T14:21:30" } "visits": [ …​ { "id": "plumber-ann", "arrivalTime": "2024-01-23T08:12:17", "startServiceTime": "2024-01-23T08:12:17", "departureTime": "2024-01-23T08:19:47", "breakDuration": null, "effectiveServiceDuration": "PT7M30S", "travelTimeFromPreviousStandstill": "PT4M47S" }, …​ ] }

totalTravelTime

string (ISO-8601 duration)

Total travel time for all vehicles in the dataset, including the new vehicle that handles the fitted visit.

"totalTravelTime": "PT15H44M10S"

totalTravelDistance

int

Total travel time in meters for all vehicles in the dataset, including the new vehicle that handles the fitted visit.

"totalTravelTime": "786858"