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

config

false

object

Configuration of the model and its run.

modelInput

true

object

The modelInput is the dataset to optimize.

2. Configuration

The configuration object contains parameters influencing the optimization process.

Id Required Format Description

run

false

object

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

model

false

object

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

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.

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.

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

maxSoftShiftEndTimeWeight

number

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

1

maxSoftLastVisitDepartureTimeWeight

number

A weight of the Max last visit departure time (soft) 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"

minimizeUnnecessarySkillsWeight

number

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

1

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

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.

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-resource visits (see visitGroups).

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.

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.

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.

travelTimeAdjustment

false

object

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

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.

8. Planning window

The planning windows specified a time range to plan for.

Id Required Format Description Example

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"

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"

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"

vehicleType

false

string

A type of the vehicle.

If omitted, "VAN" is used.

"VAN"

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

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"

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"

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"

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"

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"

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"

maxTravelTimePerVisit

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

false

array (latitude, longitude)

An end location coordinates of the vehicle shift.

If omitted, the startLocation value is assumed.

[ 52.5441475, -0.265105009 ]

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

requiredBreaks

false

array

An array of required breaks.

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

movableOccupationRatioThreshold

false

number

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

"0.5"

itinerary

false

array

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

See input itinerary item.

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"

name

false

string

A name of the visit.

If omitted, the value of id is assumed.

"Alex Pot"

location

true

array (latitude, longitude)

A location coordinates of the visit.

[ 52.0233688, 0.239470348 ],

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

serviceDuration

true

string (ISO 8601 duration)

The estimated duration of the service.

"PT15M", "PT1H30M10S"

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

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

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)

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"

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

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.

  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"

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.

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-resource 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":"NORMAL"} ],

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

minStartTime

false

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"

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"

maxEndTime

false

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"

17. Visit dependency

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

For example:

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

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

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"

minDelay

false

string (ISO 8601 duration)

A minimal delay between the two visits expressed as duration.

Mutually exclusive with delayTo.

"PT2H"

delayTo

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", "minStartTime": "08:00", "timezone": "America/New_York" }

18. Visit dependency delayTo

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"

minStartTime

false (ISO 8601 local time)

string

The time part (ISO 8601 local datetime) of the delayed visit minimum start (inclusive). The timezone 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 timezone 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"

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"

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"

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"

duration

true

string (ISO 8601 duration)

A duration of the break.

"PT1H"

location

false

array (latitude, longitude)

The location coordinates of the break

[ 52.0233688, 0.239470348 ],

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

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

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

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

run

object

The model run metadata.

See model run.

modelOutput

object

The model output containing the optimized route plan.

See model output.

kpis

object

Overall KPIs of the vehicle route plan.

See KPIs.

22. Model run

Contains metadata about the model solving 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 time the model request was accepted.

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

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"

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"

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"

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

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

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

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"

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.

26. Output itinerary item

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

27. Output itinerary item (visit)

Represents a scheduled visit in the vehicle shift itinerary.

Id Format Description Example

id

string

A reference to a visit.

"8026f548"

kind

string

Indicates the kind of the itinerary item.

VISIT

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"

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"

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"

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

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

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"

endTime

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

The end time of the scheduled break.

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

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"

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

29. Vehicle shift metrics

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

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, time and time zone offset)

The arrival time of the vehicle shift at the endLocation.

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

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

totalTravelTime

string (ISO 8601 duration)

The total travel time by all the vehicle shifts.

"PT2H15M"

travelTimeFromStartLocationToFirstVisit

string (ISO 8601 duration)

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

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

totalTravelDistanceMeters

integer

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

25000

travelDistanceFromStartLocationToFirstVisitMeters

integer

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

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

totalUnassignedVisits

number

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

10

31. Recommend Visit Time Windows API input

Description of Recommend Visit 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 (startTime inclusive, endTime exclusive).

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

modelInput

true

array

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

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

32. Recommend Visit Time Windows API output

Description of Recommend Visit 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+01:00", "endTime": "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.

statistics

object

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

See KPIs.

33. Recommend Visit Group Time Windows API input

Description of Recommend Visit Group 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 group, per each time window.

"maxNumberOfRecommendationsPerTimeWindow": 3

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"

timeWindows

true

array

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

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

modelInput

true

array

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

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

34. Recommend Visit Group Time Windows API output

Description of Recommend Visit Group Time Windows API output.

Name Format Description Example

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"

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

timeWindow

object

Time window that the recommendation ties to.

"timeWindow": { "startTime": "2024-01-23T08:00:00+01:00", "endTime": "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.

statistics

object

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

See KPIs.