Reference guide

This section describes the Field Service Routing data model.

1. Model request

The model request is the top-level object of the Field Service Routing API. It contains the configuration of the model and the dataset to optimize.

Id Required Format Description

modelInput

true

object

The modelInput is the dataset to optimize.

config

false

object

Configuration of the model and its run.

2. Configuration

The configuration object contains parameters influencing the optimization process.

Id Required Format Description

model

false

object

Configuration of the model, e.g. its constraints weights.

run

false

object

Configuration of the requested model run, e.g. its termination.

3. Run configuration

Id Required Format Description

name

false

string

Optional model run name. If omitted, a default name is generated.

termination

false

object

Model run termination configuration.

maxThreadCount

false

number

The maximum number of threads to be used for solving, must be greater than or equal to 1. The default is 1. The maximum allowed value for this model is 4.

4. Termination configuration

Id Required Format Description

spentLimit

false

string (ISO 8601 duration)

Maximum duration (e.g. PT1H) to keep the solver running.

unimprovedSpentLimit

false

string (ISO 8601 duration)

Maximum unimproved score duration. If the score has not improved during this period (e.g. PT5M), terminate the solver.

Warning: using this option will disable the default diminished returns termination which is recommended for most use cases.
Diminished returns terminates the solver early if expected improvements are minimal, saving on CPU costs. This termination is desirable since it terminates based on the relative rate of improvement, and behaves similarly on different hardware and different problem instances. You can find more details in the documentation.

5. Model configuration

Id Required Format Description

overrides

false

object

Overrides of the default model configuration.

6. Model configuration overrides

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

balanceTimeUtilizationWeight

number

A weight of the Balance technicians' workloads constraint.

1

maxSoftLastVisitDepartureTimeWeight

number

A weight of the Max last visit departure time (soft) constraint.

1

maxSoftShiftEndTimeWeight

number

A weight of the Max shift end time (soft) constraint.

1

minimizeShiftCostsWeight

number

A weight of the Minimize vehicle shift cost constraint.

1

minimizeTravelDistanceWeight

number

A weight of the Minimize travel distance constraint.

0

minimizeTravelTimeWeight

number

A weight of the Minimize travel time constraint.

1

minimizeUnnecessarySkillsWeight

number

A weight of the Minimize scheduling vehicles with unnecessary skill levels constraint.

1

minimizeVisitCompletionRiskWeight

number

A weight of the Minimize the visit completion risk constraint.

1

preferSchedulingOptionalVisitsWeight

number

A weight of the Prefer scheduling optional visits constraint.

1

preferVisitsScheduledToEarliestDayWeight

number

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

1

preferVisitVehicleMatchPreferredVehiclesWeight

number

A weight of the Prefer scheduled vehicle matches preferred vehicle constraint.

1

priorityWeights

array of PriorityConfiguration objects

An override for the priority weights. This allows for custom priorities to be set. When using this feature, no default exists, so every Visit must define a priority.

[ { priority: "NORMAL_1", weight: 30 }, { priority: "NORMAL_2", weight: 35 }, { priority: "HIGH_1", weight: 60 } ]

travelTimeAdjustment

object

An optional Travel Time Adjustment to compensate for longer travel times due to high traffic (multiplier) or difficult parking (extra constant time).

{"multiplier": 1.5, "extraTime": "PT10M" }

visitCompletionRiskMinimalPriority

string

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

"10"

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"

6.1. PriorityConfiguration

The priorityConfiguration objects require a "priority" (format: string) and a "weight" (format: int) to be set. The "priority" field will serve as the name for the priority override and the "weight" field indicates the magnitude of impact it will have. A priorityConfiguration with "weight": 50 will have an impact 5 times the size than that of a priority with "weight": 10. This means that the solver deems 1 unassigned visit with the higher priority weight equal to 5 unassigned visits with the lower priority weight.

[
{
  "priority": "E",
  "weight": 1
},
{
  "priority": "D",
  "weight": 10
},
{
  "priority": "C",
  "weight": 15
},
{
  "priority": "B",
  "weight": 50
},
{
  "priority": "A",
  "weight": 1000
}
]

7. Model Input

Represents the dataset to optimize.

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

Id Required Format Description

vehicles

true

array

An array of all vehicles including their vehicle shifts.

visits

true

array

An array of all visits that should be scheduled, excluding multi-vehicle visits (see visitGroups).

freezeDeparturesBeforeTime

false

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

The date and time with offset to UTC 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, except when manually pinning a visit by setting the visit.pinningRequested attribute to true.

locationSetName

false

string

The optional name of the set of all locations contained in this plan, used for referencing a pre-calculated location time/distance matrix to speed up processing.

If specified, all locations in the model must be a subset of the referenced pre-calculated location set.

If unspecified, a new time/distance matrix will be calculated for the request.

planningWindow

false

object

The planning window is the time interval to schedule for.

If omitted, the planning window interval is derived as follows:

- start: the minimum of all vehicle shifts minStartTime (or minFirstVisitArrivalTime when minStartTime is not defined) with time part adjusted to 00:00 (midnight).

Example: minStartTime = 2024-10-10T08:00+01:00 → start = 2024-10-10T00:00+01:00.

- end: the next day after the maximum of all vehicle shifts shiftEndTime with time part adjusted to 00:00 (midnight), where shiftEndTime is obtained as the first non-null value of the following vehicleShift attributes, in this order: maxEnd, maxLastVisitDepartureTime, shiftStartTime.

Example: shiftStartTime = 2024-10-10T08:00+01:00 → end = 2024-10-11T00:00+01:00.

skills

false

array

An array of all skill names (string) used by vehicle shifts to define the skills provided and by visits to define the skills required.

tags

false

array

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

visitGroups

false

array

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

8. Planning window

The planning windows specified a time range to plan for.

Id Required Format Description Example

endDate

true

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

An end date of the planning window (exclusive).

"2023-11-30T00:00:00+01:00"

startDate

true

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

A start date of the planning window (inclusive).

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

9. 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"

shifts

true

array

A non-empty array of all vehicle shifts planned for this vehicle.

[ {"id":"1","startLocation":[49.288087,16.562172],"shiftStartTime":"2024-03-21T08:00:00+01:00"}]

historicalTimeUtilized

false

string (ISO 8601)

The duration the vehicle has been used in the past. This will be considered in the fairness computation.

If omitted, "PT0S" is used.

"PT2400M"

historicalTimeCapacity

false

string (ISO 8601)

The duration the vehicle was available in the past. This will be considered in the fairness computation.

If omitted, "PT0S" is used.

"PT2400M"

vehicleType

false

string

A type of the vehicle.

If omitted, "VAN" is used.

"VAN"

10. 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"

startLocation

true

array (latitude, longitude)

A start location coordinates of the vehicle shift.

[ 52.5441475, -0.265105009 ]

minFirstVisitArrivalTime

false (one of minStartTime and minFirstVisitArrivalTime is required)

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

A minimum date and time when the vehicle shift is supposed to arrive to its first visit.

The value of minFirstVisitArrivalTime (if set) must be after minStartTime.

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

minStartTime

false (one of minStartTime and minFirstVisitArrivalTime is required)

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

A minimum date and time when the vehicle shift can start.

The value of minStartTime (if set) must be before or equal to minFirstVisitArrivalTime.

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

cost

false

object

An optional Vehicle Shift Cost definition.

{ "fixedCost": 50.0, "rates": [ { "duration": "PT8H", "activationCost": 10.0, "costPerUnit": 20.0, "unit": "HOUR" } ] }

endLocation

false

array (latitude, longitude)

An end location coordinates of the vehicle shift.

If omitted, the startLocation value is assumed.

[ 52.5441475, -0.265105009 ]

itinerary

false

array

An array of itinerary items ordered by their scheduled arrival or start.

See input itinerary item.

maxEndTime

false

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

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

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

maxLastVisitDepartureTime

false

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

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

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

maxSoftEndTime

false

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

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

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

maxSoftLastVisitDepartureTime

false

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

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

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

maxTravelTimePerVisit

false

string (ISO 8601 duration)

A maximal travel time limit per visit (hard).

"PT1H"

movableOccupationRatioThreshold

false

number

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

"0.5"

requiredBreaks

false

array

An array of required breaks.

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

skills

false

array

An array of skill definitions which this vehicle shift provides.

[{"name": "plumber", "level": 1, "multiplier": 1.0}]

tags

false

array

An array of tag references.

["emergency"]

temporarySkillSets

false

array

Skills that are applicable within specified time intervals only.

[ { "start": "2023-11-27T09:00:00+01:00", "end": "2023-11-27T13:00:00+01:00", "skills": [{"name": "plumber", "level": 10}] }

temporaryTagSets

false

array

Tags that are applicable within specified time intervals.

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

11. Input itinerary item

Represents a visit or a break in the vehicle shift itinerary. Use to define already scheduled visits or breaks from previous planning.

Id Format Required Description Example

id

string

true

A reference to a visit or a break.

"8026f548"

kind

string

true

Indicates the kind of the itinerary item. Either VISIT or BREAK.

VISIT

12. 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"

location

true

array (latitude, longitude)

A location coordinates of the visit.

[ 52.0233688, 0.239470348 ],

serviceDuration

true

string (ISO 8601 duration)

The estimated duration of the service.

"PT15M", "PT1H30M10S"

minStartTravelTime

false

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

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' minStartTravelTime.

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 minStartTravelTime values of pinned visits to calculate their arrivalTime correctly, b.calculate minStartTravelTime values for the unpinned visits to ensure they are assigned into the time period after the freezeDeparturesBeforeTime.

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

name

false

string

A name of the visit.

If omitted, the value of id is assumed.

"Alex Pot"

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)

priority

false

string

Defines priority for visit assignment. There are 10 built-in priorities where "1" is the highest priority and "10" is the lowest priority. Default built-in priority is "6". These built-in priorities use exponential penalty weights, where priority "1" is 10 times more important than priority "2", priority "2" is 10 times more important than priority "3" and so on. Optionally, you can override these weights, or define custom priorities in the model configuration overrides. In case the custom priorities are used, there is no default value for the priority attribute, and you need to provide a value.

"5"

serviceDurationAdjustment

false

string (ISO 8601 duration)

The adjustment of the serviceDuration. Can be negative.

Deprecated, will be removed in the next version.

"PT15M"

serviceDurationBreakdown

false

array

The visit serviceDuration breakdown by individual trades (skills).

The sum of durations for all skills specified here must not be greater than the value of serviceDuration. It can be less which allows for leaving a part of the job duration uncategorized - please note that the uncategorized part will not be adjusted by skill multipliers, but it will be added to the result (with multiplier 1.0).

[ { "skill": "plumber", "duration": "PT1H" }, { "skill": "carpenter", "duration": "PT30M" } ]

timeWindows

false

array

An array of time windows defining the time intervals when this visit can be performed by a vehicle shift.

Please note that visit’s individual time windows must not overlap.

If omitted, a single time window with default values is assumed.

[ { "minStartTime": "2023-11-27T10:00:00+01:00", "maxEndTime": "2023-11-27T10:00:00+01:00" }, { "minStartTime": "2023-11-27T10:00:00+01:00", "maxStartTime": "2023-11-27T10:00:00+01:00", "maxEndTime": "2023-11-27T10:00:00+01:00" } ]

requiredSkills

false

array

An array of skill requirements for this visit.

[{"name": "plumber", "minLevel": 1}]

requiredTags

false

array

An array of tag references required by this visit.

["north", "emergency"]

requiredVehicles

false

array

An array of vehicle references (ids) required by this visit.

In other words, this visit can be assigned only to a shift of one of the specified vehicles.

If empty, the visit can be assigned to a vehicle shift of any vehicle (default).

["Carl", "Beth"]

visitDependencies

false

array

An array of visit dependencies.

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

13. Visit Group

A visit group represents a multi-vehicle visit, i.e. a group of individual service jobs that need to be performed at customer location at the same time.

13.1. Visit Group scenarios

A visit group may be used to model different scenarios:

  1. Multiple vehicles need to perform a service job S at the same customer at the same time. We do not care about their skills, or they have the same set of skills - all we need is to synchronize multiple vehicles over a single customer visit. How to model:

    • Create a visit for each part of the service job that needs to be assigned to a single vehicle.

    • Set the created visit’s serviceDuration to the duration of the original service job S.

    • Create a visit group with either omitted, or the default serviceDurationStrategy = INDIVIDUAL, containing all the visits created in the previous step.

    • By default, the assigned vehicles start the service job at the same time. However, you can set the alignment to END to make the vehicles depart at the same moment instead.

  2. Multiple vehicles with different skills (e.g. an electrician and a carpenter) and skill proficiency levels need to perform a service job at the same customer at the same time. How to model:

    • Create a visit for each part of the service job that needs to be assigned to a single vehicle.

    • Set the created visit’s serviceDuration to the duration of the corresponding part of the original service job only.

    • Create a visit group with serviceDurationStrategy = INDIVIDUAL containing all the visits created in the previous step.

  3. Multiple vehicles with different skills (e.g. an electrician and a carpenter) need to perform a service job at the same customer at the same time, while the best skill proficiency (among all vehicles) determines the effective service duration of each visit in the group. How to model:

    • Create a visit for each part of the service job that needs to be assigned to a single vehicle.

    • Set the created visit’s serviceDuration to the duration of the corresponding part of the original service job only.

    • Create a visit group with serviceDurationStrategy = BEST_PROFICIENCY containing all the visits created in the previous step.

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"

alignment

false

string

The alignment of the visits in the visit group:

START: aligns visits to the same startServiceTime (default) END: aligns visits to the same departureTime

"END"

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 a visit in a service group requires a technician to have multiple skills, the average of the proficiency modifiers 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.

Important: In scenarios 2 and 3, the visits' serviceDuration attribute is expected to be already adjusted to the fact that this service is handled by multiple technicians.

In other words, consider a single-resource visit taking one hour. When it is converted to a multi-vehicle visit (a visit group) formed by e.g. two visits, each of them is expected to have a shorter serviceDuration than one hour, taking into account that two resources (technicians) can handle the service faster.

[ {"id":"1abcd","name":"John","location":[49.288087,16.562172],"timeWindows": [{"minStartTime":"2024-02-23T08:00:00+01:00","maxEndTime":"2024-02-23T12:00:00+01:00"}],"serviceDuration":"PT1H","priority":"9"} ],

14. Skills

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

14.1. Skill definition

A skill definition specifies the skill name, its level and a potential service duration multiplier for a vehicle shift.

Id Required Format Description Example

name

true

string

A unique string identifier of the skill. Must be declared in the input top-level skills attribute.

"plumber"

level

false

number

A positive integer >= 1 defining the skill level (the higher, the better). The skill can be matched only to a skill requirement which has a lower or equal minLevel.

The default value is 1.

10

multiplier

false

float

A float visit service duration multiplier, the assigned visit’s service duration is multiplied with this multiplier to reflect a particular vehicle shift’s skill level.

The default value is null meaning this skill will not affect any service duration calculations (the value of 1.0 can still affect calculation of average duration of visits in a visit group).

0.8

14.2. Skill requirement

A skill requirement specifies the skill name and the minimum skill level required from the vehicle shift assigned to this visit.

Id Required Format Description Example

name

true

string

A unique string identifier of the skill. Must be declared in the input top-level skills attribute.

"plumber"

minLevel

false

number

A positive integer >= 1 defining the required skill level (the higher, the better). The default value is null, meaning this skill does not care about skill level at all.

10

15. Tag

Tags connect visits with the right vehicle shift. For instance, a visit may require a vehicle shift for specific region, 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.

"emergency"

16. Visit time window

A visit time window represents a continuous time interval when a visit can be performed. See Time windows and opening hours section for additional details.

Id Required Format Description Example

maxEndTime

true

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

A maximum end time of the visit (exclusive).

If omitted, the planning window end date is assumed.

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

maxStartTime

false

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

A maximum start time of the visit (exclusive).

If omitted, null (no maximum start time) is assumed.

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

minStartTime

true

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

A minimum start time of the visit (inclusive).

If omitted, the planning window start date is assumed.

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

17. Visit dependency

A visit can declare a dependency on some other visit, specifying a minimal delay or additional conditions to hold between them. The minimal delay can be specified either as a duration (minDelay attribute) or as a reference to future point in time (minDelayTo attribute). The conditions can be specified using the coordination attribute.

For example:

  • (minDelay) a technological break between two maintenance tasks needs to last at least 12 hours.

  • (minDelayTo) a follow-up task can be performed no sooner than on the first day of the next week due to specific customer requirements.

  • (coordination) a follow-up task must be serviced by the same vehicle (not the same vehicle shift).

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"

coordination

false

string

Additional coordination requirements between the two visits.

Supported values: NONE (default), SAME_VEHICLE.

"SAME_VEHICLE"

minDelay

false

string (ISO 8601 duration)

A minimal delay between the two visits expressed as duration.

Mutually exclusive with minDelayTo.

"PT2H"

minDelayTo

false

object

A minimal delay between the two visits expressed as a reference to future point in time.

Mutually exclusive with minDelay.

{ "minStartDateAdjuster": "NEXT_DAY", "minStartDateAdjusterIncrement": 1, "minStartTime": "08:00", "timezone": "America/New_York" }

18. Visit dependency minDelayTo

A reference to a future point in time when a dependent visit can start at the earliest.

Id Required Format Description Example

minStartDateAdjuster

true

string

The name of the adjuster function for the date part of the delayed visit minimum start.

The following functions are supported:

SAME_DAY, NEXT_DAY, NEXT_MONTH,

NEXT_MONDAY, NEXT_TUESDAY, NEXT_WEDNESDAY, NEXT_THURSDAY, NEXT_FRIDAY, NEXT_SATURDAY, NEXT_SUNDAY.

"NEXT_DAY", "NEXT_MONTH", "NEXT_MONDAY"

minStartDateAdjusterIncrement

false

integer

The increment which determines how many times minStartDateAdjuster is applied. The default value is 1.

2, 4, 7

minStartTime

false (ISO 8601 local time)

string

The time part (ISO 8601 local datetime) of the delayed visit minimum start (inclusive). The time zone offset is taken either from the source date time, or from the timezone attribute, if supplied.

The default value is midnight (start of day): 00:00

"08:00"

timezone

false

string

The optional region-based TZDB identifier of the time zone which rules apply to the minStartDateAdjuster and minStartTime combination.

If omitted, the zone offset of the source date time (i.e. the visit dependency departureTime) for the adjustment is kept. To handle DST changes, supply the timezone too.

"America/New_York", "Europe/Brussels"

19. Required break

Represents a break during a vehicle shift. The break can either be fixed (minStartTime and maxStartTime are equal) or floating (maxStartTime is not given). Optionally, the break can specify a location, in which case the solver will try to minimize the travel time to the location of the break.

A fixed break delays the arrival time to the visit after the break by the duration of the break.

A floating break is scheduled towards the next visit and does not delay the arrival time, assuming the break is taken after the travel. The visit’s effective start time is used to determine if the floating break should be applied. Thus, in case of waiting between the arrival and the effective start time, the break is applied even before its minStartTime.

Id Required Format Description Example

id

true

string

A unique string identifier of the break.

"353"

duration

true

string (ISO 8601 duration)

A duration of the break.

"PT1H"

minStartTime

true

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

The earliest time to schedule the break at.

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

costImpact

false

enum ("PAID")

The impact of this break on the vehicle shift cost calculation.

Currently only PAID (default) is supported, meaning that the break duration is included in the vehicle shift paid time.

"PAID"

location

false

array (latitude, longitude)

The location coordinates of the break

[ 52.0233688, 0.239470348 ],

maxEndTime

false

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

The latest time the break should end at.

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

maxStartTime

false

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

The latest time to schedule the break at.

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

20. Vehicle Shift Cost

Every vehicle shift can have a cost that has to be paid when the vehicle shift has at least one visit assigned.

All vehicle shift breaks are considered paid at the moment.

The cost definition consists of:

  • fixedCost is the fixed cost of having a vehicle available for a shift, even if the vehicle has no visits assigned during the shift.

  • rates is the list of cost rates applied to the vehicle shift after a certain amount of time passes from the shift start:

    • The first rate in the list (rate1): rate1.start = shift start time and rate1.end = rate1.start + rate1.duration.

    • The second rate (rate2): rate2.start = rate1.end and rate2.end = rate1.end + rate2.duration.

    • The same principle applies to the other rates in the list, except for the last rate end which is always assumed to be the end of the shift.

Id Required Format Description Example

fixedCost

false

number (BigDecimal)

The fixed cost of having a vehicle available for a shift, even if the vehicle has no visits assigned during the shift.

The default value is 0.0.

100.0

rates

false

array

The list of cost rates applied to the vehicle shift after a certain amount of time passes from the shift start.

The default value is empty list.

[ { "duration": "PT8H", "activationCost": 10, "costPerUnit": 20, "unit": "HOUR" } ] to pay 10 + (20 per every started shift hour)

21. Vehicle Shift Cost Rate

Every vehicle shift cost can define a list of rates. Every rate:

  • Starts from the end of the previous rate, or the start of the vehicle shift, if there is no previous rate.

  • Has a duration.

  • Has an activationCost paid once when this rate has started.

  • Defines a cost per unit (HOUR/MINUTE) that is applied to every started unit (HOUR/MINUTE) within this rate’s duration.

For example, to define a standard 8-hour cost as 100.0 per hour and the next 4 hours (overtime) cost as twice as much, use the following rate list:

  [
    { "duration": "PT8H", "costPerUnit": 100.0, "unit": "HOUR" },
    { "duration": "PT4H", "costPerUnit": 200.0, "unit": "HOUR" }
  ]

If the vehicle shift duration exceeds the last defined rate’s duration, the last rate is used for the remaining shift duration as well.

Id Required Format Description Example

duration

true

string (ISO 8601 duration)

The duration of this rate.

"PT8H"

activationCost

false

number (BigDecimal)

The activation cost paid once when this rate has started.

The default value is 0.0.

100.0

costPerUnit

false

number (BigDecimal)

The cost paid per time unit during this rate.

The default value is 0.0.

10.0

unit

false

enum ("HOUR", "MINUTE")

The time unit that is paid by costPerUnit. Every started time unit is paid (e.g. in case of HOUR, having worked for 1 hour and 10 minutes within this rate results in 2 hours paid).

The default value is "HOUR".

HOUR

22. Travel Time Adjustment

Travel time adjustment can be defined to implement a "buffer" allowing for unexpected traffic delays or long parking time when travelling.

The travel time adjustment is configured as a function for every route between any two locations as follows:

adjustedTravelTime = multiplier * mapTravelTime + extraTime,

where:

  • mapTravelTime is the travel time obtained from a map service,

  • multiplier and extraTime are the travel time adjustment attributes described below.

Id Required Format Description Example

extraTime

false

string (ISO 8601 duration)

The additional time to add to the original travel time obtained from a map service. Must be positive or zero duration.

The default value is "PT0S" (zero duration).

"PT5M" - to add extra 5 minutes to every route travel time

multiplier

false

float

The coefficient to multiply the original travel time obtained from a map service with. Must be greater than zero (typically will be greater than 1 to make the travel time longer).

The default value is 1.0.

1.1 to achieve 10 % longer travel times

23. Model response

The response to the model request is the optimized route plan, metadata about the model run, and key performance indicators (KPIs).

Id Format Description Example

kpis

object

Overall KPIs of the vehicle route plan.

See KPIs.

modelOutput

object

The model output containing the optimized route plan.

See model output.

run

object

The model run metadata.

See model run.

24. Model run

Contains metadata about the model solving run.

The run is associated with five key timestamps, each marking a distinct phase in the process:

  • submitDateTime: The moment the run is submitted. At this stage, the run is queued and has not yet begun solving. The run status is SOLVING_SCHEDULED.

  • startDateTime: The moment the run begins initializing. During this phase, the run is not solving yet, but the model is being built and enriched with external data (e.g., incorporating map information for models involving geographical locations). The run status is SOLVING_STARTED.

  • activeDateTime: The moment the solving phase begins. At this stage, the actual problem-solving process starts. The run status is SOLVING_ACTIVE.

  • completeDateTime: The moment the solving phase concludes. At this point, the run has finished solving but has not yet undergone any post-processing (e.g., score analysis or waypoint enrichment for geographical models). The run status is either SOLVING_COMPLETED or SOLVING_FAILED.

  • shutdownDateTime: The moment the post-processing phase finishes. All tasks, including post-processing, are completed, and the run is fully finalized.

Id Format Description Example

activeDateTime

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

The time solving the model changed to active state.

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

completeDateTime

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

The time solving the model request completed.

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

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"

score

string

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

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

shutdownDateTime

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

The time solving the model solution was stored.

"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"

startDateTime

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

The time solving the model request started.

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

submitDateTime

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

The time the model request was accepted.

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

25. Model output

The model output is a counterpart to the model input and represents the optimized route plan. The model output contains only the assignments of visits to vehicle shifts and does not repeat the input data.

Id Format Description Example

vehicles

array

The list of plans per vehicle.

See vehicle plan.

26. Vehicle plan

The vehicle plan groups plans for individual vehicle shifts of a single vehicle.

Id Format Description Example

id

String

ID of the vehicle from the model input.

See vehicle.

shifts

array

The list of plans per vehicle shift.

See vehicle shift plan.

27. Vehicle shift plan

The vehicle shift plan contains the optimized route plan (itinerary) for a single vehicle shift, as well as metrics of the route plan.

Id Format Description Example

id

String

ID of the vehicle shift from the model input.

See vehicle shift.

itinerary

array

An array of itinerary items ordered by their scheduled arrival or start.

See output itinerary item.

metrics

object

Metrics of the vehicle shift route.

See vehicle shift metrics.

startTime

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

The planned start date and time of the vehicle shift.

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

28. Output itinerary item

The itinerary item represents either a visit or a break in the vehicle shift itinerary.

29. Output itinerary item (visit)

Represents a scheduled visit in the vehicle shift itinerary.

Id Format Description Example

arrivalTime

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

The arrival time of the vehicle at the customer location.

"2023-11-27T11:10:09+01:00"

departureTime

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

The end of the service at the customer location.

"2023-11-27T11:25:09+01:00"

effectiveServiceDuration

string (ISO 8601 duration)

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

"PT15M"

id

string

A reference to a visit.

"8026f548"

kind

string

Indicates the kind of the itinerary item.

VISIT

startServiceTime

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

The beginning of the service at the customer location.

"2023-11-27T11:10:09+01:00"

travelDistanceMetersFromPreviousStandstill

integer

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

5000

travelTimeFromPreviousStandstill

string (ISO 8601 duration)

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

"PT10M3S"

30. Output itinerary item (break)

Represents a scheduled break in the vehicle shift itinerary.

Id Format Description Example

id

string

A reference to a break.

"8026f548"

endTime

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

The end time of the scheduled break.

"2023-11-27T11:10:09+01:00"

kind

string

Indicates the kind of the itinerary item.

BREAK

startTime

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

The start time of the scheduled break.

"2023-11-27T11:10:09+01:00"

travelDistanceMetersFromPreviousStandstill

integer

The travel distance either from the previous visit or from the start location of the vehicle shift. Applies only to breaks with a location.

5000

travelTimeFromPreviousStandstill

string (ISO 8601 duration)

The travel time either from the previous visit or from the start location of the vehicle shift. Applies only to breaks with a location.

"PT10M3S"

31. Vehicle shift metrics

The vehicle shift metrics capture the performance of a single vehicle shift route plan.

Id Format Description Example

endLocationArrivalTime

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

The arrival time of the vehicle shift at the endLocation.

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

overtime

string (ISO 8601 duration)

The amount of overtime required for this vehicle shift.

The amount of overtime for a shift is the sum of the time ranges between: 1. maxSoftEndTime and endLocationArrivalTime, or 2. maxSoftLastVisitDepartureTime and departureTime of the last visit assigned to the shift.

The overtime of a shift is null when the shift has both maxSoftEndTime and maxSoftLastVisitDepartureTime set to null (no overtime rules are defined).

PT1H10M

technicianCosts

number (BigDecimal)

The technician costs of this vehicle shift. Null when no costs are defined for this vehicle shift.

"100.0"

totalTravelDistanceMeters

integer

The total travel distance by the vehicle shift in meters.

25000

totalTravelTime

string (ISO 8601 duration)

The total travel time by the vehicle shift.

"PT2H15M"

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

travelDistanceFromStartLocationToFirstVisitMeters

integer

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

3000

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"

travelTimeFromStartLocationToFirstVisit

string (ISO 8601 duration)

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

"PT10M"

32. Key performance indicators (KPIs)

The key performance indicators (KPIs) of the entire route plan. These top-level metrics provide an overview of the route plan quality.

Id Format Description Example

assignedMandatoryVisits

number

The number of mandatory visits assigned in this schedule.

10

assignedOptionalVisits

number

The number of optional visits assigned in this schedule.

10

totalActivatedVehicles

number

The number of vehicles used in this schedule.

10

totalAssignedVisits

number

The number of visits assigned in this schedule.

10

totalOvertime

string (ISO 8601 duration)

The amount of overtime required for this schedule.

The amount of overtime for the schedule is the sum of each vehicle shift overtime.

The total overtime is null when all shifts have both maxSoftEndTime and maxSoftLastVisitDepartureTime set to null (no overtime rules are defined).

PT1H10M

totalTechnicianCosts

number (BigDecimal)

The total costs of all technicians (if defined) in the plan.

Null when there is no vehicle shift with costs defined.

"1000.5"

totalTravelDistanceMeters

integer

The total travel distance by the vehicle shift in meters summed for all vehicle shifts.

25000

totalTravelTime

string (ISO 8601 duration)

The total travel time by all the vehicle shifts.

"PT2H15M"

totalUnassignedVisits

number

The number of visits that could not be assigned a vehicle in this schedule.

10

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, summed for all vehicle shifts.

20000

travelDistanceFromLastVisitToEndLocationMeters

integer

The travel distance from the last visit to the end location in meters summed for all vehicle shifts.

2000

travelDistanceFromStartLocationToFirstVisitMeters

integer

The travel distance from the start location to the first visit in meters summed for all vehicle shifts.

3000

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, summed for all vehicle shifts.

"PT2H"

travelTimeFromLastVisitToEndLocation

string (ISO 8601 duration)

The travel time from the last visit to the end location summed for all vehicle shifts.

"PT5M"

travelTimeFromStartLocationToFirstVisit

string (ISO 8601 duration)

The travel time from the start location to the first visit summed for all vehicle shifts.

"PT10M"

workingTimeFairnessPercentage

percentage

Describes how balanced a solution is in terms of time worked of technicians. The higher the percentage is, the more balanced the time worked is distributed among technicians.

"95.98"

33. Recommend Visit Time Windows API input

Description of Recommend Visit Time Windows API input.

Name Required Format Description Example

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"

maxNumberOfRecommendationsPerTimeWindow

true

int

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

"maxNumberOfRecommendationsPerTimeWindow": 3

modelInput

true

array

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

`"modelInput": { "name": "BASIC", "vehicles": [ { "id": "1", "vehicleType": "VAN" }, `

timeWindows

true

array

Time windows to get the vehicle shift recommendations for (minStartTime and maxStartTime inclusive, maxEndTime exclusive).

`"timeWindows": [ { "minStartTime":"2024-01-23T08:00:00+01:00", "maxStartTime":null, "maxEndTime":"2024-01-23T18:00:00+01:00" }, { "minStartTime":"2024-01-23T12:00:00+01:00", "maxStartTime":"2024-01-23T12:00:00+01:00", "maxEndTime":"2024-01-23T13:00:00+01:00" }, ] `

includeDependencies

false

string

Which dependencies should be included in the response of the recommendation. Possible values are: ALL, NONE

"includeDependencies": "ALL"

34. Recommend Visit Time Windows API output

Description of Recommend Visit Time Windows API output.

Name Format Description Example

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" }, …​ `

dependentVehicleShifts

array

Dependent vehicle shifts for the time window and the visit to fit. These shifts might be influenced by the recommendation.

See vehicle shift plan.

scoreDiff

string

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

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

statistics

object

KPIs of the route plan with the fitted visit as per this recommendation.

See KPIs.

timeWindow

object

Time window that the recommendation ties to.

"timeWindow": { "minStartTime":"2024-01-23T08:00:00+01:00", "maxStartTime":null, "maxEndTime":"2024-01-23T18:00:00+01:00" }

vehicleShifts

array

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

See vehicle shift plan.

35. Recommend Visit Group Time Windows API input

Description of Recommend Visit Group Time Windows API input.

Name Required Format Description Example

fitVisitGroupId

true

string

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

"fitVisitGroupId": "plumber-ann"

maxNumberOfRecommendationsPerTimeWindow

true

int

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

"maxNumberOfRecommendationsPerTimeWindow": 3

modelInput

true

array

Input route plan that contains a visit group with identifier specified by fitVisitGroupId attribute.

`"modelInput": { "name": "BASIC", "vehicles": [ { "id": "1", "vehicleType": "VAN" }, …​ `

timeWindows

true

array

Time windows to get the vehicle shift recommendations for (startTime inclusive, endTime exclusive).

`"timeWindows": [ { "minStartTime":"2024-01-23T08:00:00+01:00", "maxStartTime":null, "maxEndTime":"2024-01-23T18:00:00+01:00" }, { "minStartTime":"2024-01-23T12:00:00+01:00", "maxStartTime":"2024-01-23T12:00:00+01:00", "maxEndTime":"2024-01-23T13:00:00+01:00" }, ] `

includeDependencies

false

string

Which dependencies should be included in the response of the recommendation. Possible values are: ALL, NONE

"includeDependencies": "ALL"

36. Recommend Visit Group Time Windows API output

Description of Recommend Visit Group Time Windows API output.

Name Format Description Example

constraintDiffs

array

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

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

dependentVehicleShifts

array

Dependent vehicle shifts for the time window and the visit group to fit. These shifts might be influenced by the recommendation.

See vehicle shift plan.

scoreDiff

string

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

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

statistics

object

KPIs of the route plan with the fitted visit as per this recommendation.

See KPIs.

timeWindow

object

Time window that the recommendation ties to.

"timeWindow": { "minStartTime":"2024-01-23T08:00:00+01:00", "maxStartTime":null, "maxEndTime":"2024-01-23T18:00:00+01:00" }

vehicleShifts

array

Vehicle shift recommendations for the time window and the visit group to fit.

See vehicle shift plan.