xtour

XTour Operations

SOAP/JSON

Synchronous API

since 2.1
Operation Name Request Type Response Type Since Description
planTours PlanToursRequest ToursResponse 2.1 Plan tours that ideally include all orders that are specified in the request. Returns a plan with tours and reports with additional information about the planned tours.
changeTours ChangeToursRequest ToursResponse 2.5 Change existing tours via specified actions. Returns a plan containing the changed tours and reports with additional information about those changed tours. The source tour(s) and target tour are always returned even if the tours did not change (for example if an addTripAction with an insertion position of type insertion at best position does not find a valid insertion position). Furthermore the stored request will be the original PlanToursRequest with changed tours information contained in the input plan.
findChangeToursProposals FindChangeToursProposalsRequest ChangeToursProposalsResponse 2.14 Propose ChangeToursActions to change an existing tour plan as desired. Returns proposed ChangeToursActions with resulting TourReports if the corresponding ChangeToursAction would be applied via a ChangeToursRequest.
evaluateToursInExecution ToursInExecutionRequest ToursResponse 2.21 Calculate time profile for a tour in execution. Returns tour reports containing the time profile starting at the current position of each specified vehicle.
SOAP/JSON

Asynchronous API

since 2.1
Operation Name Request Type Response Type Since Description
startPlanTours PlanToursRequest Job 2.1

This is the asynchronous version of planTours.

Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchToursResponse. If the job ended with status FAILED, fetchToursResponse throws the exception that occurred during calculation.

startChangeTours ChangeToursRequest Job 2.5

This is the asynchronous version of changeTours.

Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchToursResponse. If the job ended with status FAILED, fetchToursResponse throws the exception that occurred during calculation.

startFindChangeToursProposals FindChangeToursProposalsRequest Job 2.14

This is the asynchronous version of findChangeToursProposals.

Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchChangeToursProposalsResponse. If the job ended with status FAILED, fetchChangeToursProposalsResponse throws the exception that occurred during calculation.

startEvaluateToursInExecution ToursInExecutionRequest Job 2.21

This is the asynchronous version of evaluateToursInExecution.

Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchToursResponse. If the job ended with status FAILED, fetchToursResponse throws the exception that occurred during calculation.

fetchChangeToursProposalsResponse JobRequest ChangeToursProposalsResponse 2.14

Fetches results of type ChangeToursProposalsResponse for the given job. If the calculation ended with an exception, fetchChangeToursProposalsResponse will rethrow it. If the id of the job is unknown, a XServerException with message 'unknown id' is thrown.

fetchToursResponse JobRequest ToursResponse 2.1

Fetches results of type ToursResponse for the given job. If the calculation ended with an exception, fetchToursResponse will rethrow it. If the id of the job is unknown, a XServerException with message 'unknown id' is thrown.

watchJob WatchRequest Job 2.1

Returns the status of the given job.

This operation behaves exactly like the watchJob operation of the xRuntime service.

stopJob JobRequest Job 2.1

Attempts to stop a running job. If the status of the job changes to SUCCEEDED, preliminary results can be fetched, if available.

This operation behaves exactly like the stopJob operation of the xRuntime service.

deleteJob JobRequest Job 2.1

Attempts to delete a running job. If successful, the returned job will have state DELETED.

This operation behaves exactly like the deleteJob operation of the xRuntime service.

Types

AddFixationsAction

extends ChangeToursAction
since 2.7

A specific action to add fixations to the current plan. If at least one of the fixations references the ID of a nonexistent object, an exception is thrown and none of the fixations is added. If one of the fixations is already existing in the current plan, no exception is thrown but the fixation is just ignored.

Field Name Type Required Default Since Description
fixations Fixation[] 1..* - 2.7 Fixations to be added to the current plan.

AddTripAction

extends ChangeToursAction
since 2.8

A specific action to create a single trip of specified orders for a specified vehicle instance. The trip can be created for an unplanned vehicle or within a tour of an already planned vehicle. For an AddTripAction at a specified position a trip of at least one order is created even if the resulting tour becomes invalid but remains structurally valid.

Field Name Type Required Default Since Description
orderIds String[] 1..* - 2.8 IDs of orders from which a trip is created. Orders that cannot be planned end up in orderIdsNotPlanned after performing the AddTripAction. All referenced orders need to be unplanned.
targetVehicleId String yes - 2.8 ID of the vehicle for that a trip is added. The vehicle can be empty or already have a tour with one or more trips assigned.
insertionPosition InsertionPosition yes - 2.8 InsertionPosition of the trip that is added. If InsertionPosition is of type InsertionAtBestPosition, orders in orderIds that can not be moved to the target vehicle are listed in a NoValidInsertionPositionFoundLimitation as objectIds.

AddTripStartIntervalsAction

extends ChangeToursAction
since 2.19

A specific action to add trip start intervals to the current plan. If at least one of the trip start intervals references the trip ID of a nonexistent trip or if a trip start interval is added again for the same trip ID, an exception is thrown and none of the trip start intervals is added.

Field Name Type Required Default Since Description
tripStartIntervals TripStartInterval[] 1..* - 2.19 TripStartIntervals to be added to the current plan.

BreakInterval

used by Driver
since 2.19

A break interval is a time interval together with the required duration of the break that shall be scheduled within the interval. Such a break may be scheduled en route between stops. Due to the fact that service time is never split, the driver may have to wait at a stop for the beginning of the next break interval and only begin with the service after the break.

Field Name Type Required Default Since Description
interval Interval yes - 2.19 Interval within which the driver wants or needs to take a break. Interval must be at least as long as the break time.
breakTime Duration (double) yes - 2.19 The duration of the break to be scheduled within the interval. Must be greater than 0.

The abstract base type for all specified actions to change tours.

Field Name Type Required Default Since Description
storedRequestId String yes - 2.5 ID of the stored PlanToursRequest that contains all information about the tours to be changed as input plan. This request with changed input plan containing the tours information after the ChangeToursAction will be again stored in the session storage and the ID of the stored request will be returned as stored request.

ChangeToursProposal

used by ChangeToursProposalsResponse
since 2.14

A ChangeToursProposal contains a ChangeToursAction with information about the resulting ToursResponse if the change would be applied to the tour plan.

Field Name Type Required Default Since Description
changeToursAction ChangeToursAction no - 2.14 The proposed ChangeToursAction that could be applied to the tour plan via a ChangeToursRequest.
tours Tour[] 0..* - 2.14 Resulting tours if the proposed ChangeToursAction would be applied. Dependent on the ChangeToursProposalsQuery different tours are part of the result. At least the target tour of the ChangeToursAction is contained in these tours.
tourReports TourReport[] 0..* - 2.14 TourReports corresponding to the tours.
vehicleIdsNotPlanned String[] 0..* - 2.14 References to vehicle instances that were planned before but would no longer be planned after performing the ChangeToursAction. These vehicles are not part of the tours.
violated Boolean no - 2.14 True if there is any tour violation.
preferencesRespected Boolean no - 2.14 True if all preferences for order group consideration and single stop per customer site are respected.

ChangeToursProposalsOptions

used by FindChangeToursProposalsRequest
since 2.14

Options for the propose ChangeToursAction operation.

Field Name Type Required Default Since Description
returnViolatedTours Boolean no false 2.14 Set to true if the response should also contain target tours with TourViolation.

ChangeToursProposalsQuery (abstract)

extended by InsertionPositionsForOrdersQuery, VehiclesForTripsQuery
used by FindChangeToursProposalsRequest
since 2.14

The abstract base type for all specified actions to propose ChangeToursActions.

Field Name Type Required Default Since Description
storedRequestId String yes - 2.14 ID of the stored PlanToursRequest that contains all information about the tours that could be changed as input plan. This request does not actually change the plan but just proposes changes. Thus, no new object is stored in the session storage.

ChangeToursProposalsResponse

extends ResponseBase
used by XTour
since 2.14

Contains the result of a FindChangeToursProposalsRequest.

Field Name Type Required Default Since Description
proposals ChangeToursProposal[] 0..* - 2.14 Each element contains a ChangeToursAction with more information about the resulting tour plan if the change would be applied. The list is sorted increasingly according to the internal objective function considering the overall travel and driving time of tours. If returnViolatedTours is true, then proposals might contain target tours with TourViolation. These are sorted to the back. The list can be empty if no structurally valid proposal can be found.

ChangeToursRequest

extends RequestBase
used by XTour
since 2.5

The request object for the service method changeTours. For further information please have a look at the technical concept Change Tours.

Field Name Type Required Default Since Description
changeToursAction ChangeToursAction yes - 2.5 An action that changes the existing tours in a specified way. If the action leads to any not explicitly specified new trips or to a trip merge, an exception is thrown.

ChangeVehicleAction

extends ChangeToursAction
since 2.5

A specific action to change the vehicle of a tour. Either an unused vehicle can be assigned to a tour or a vehicle swap between two tours can be executed with this action. The assignment of drivers to vehicles remains unchanged, i. e. the driver changes together with the vehicle.

Field Name Type Required Default Since Description
currentVehicleId String yes - 2.5 ID of the current vehicle of the tour.
targetVehicleId String yes - 2.5 ID of the target vehicle of the tour.

CompartmentAccessRestriction

used by Vehicle
since 2.29

The compartment access restriction is needed if the corresponding vehicle has two special compartments, called compartments A and B in the following, and one compartment can only be accessed through the other compartment. It is specified for each maximum quantity scenario of the corresponding vehicle whether compartment A can only be accessed through compartment B or the other way around. In order to access the separate compartment (whether A or B) for picking up goods or delivering them, the load in the walk-through compartment (whether B or A) in relation to its capacity must not exceed a certain load threshold. If this restriction is used, the compartment quantity indices must also be set. The restriction is complied with if a feasible sequence of the pickup and delivery operations exists at every stop (first unloading the walk-through compartment, then unloading the separate compartment, then loading the separate compartment, then loading the walk-through compartment). However, the tasks of a stop do not get sorted accordingly. See the technical concept page for details on the compartment access restriction.

Field Name Type Required Default Since Description
loadThresholdToAccessAThroughB Percent (Double) no - 2.29 Provided that compartment A can only be accessed through compartment B, the load in compartment B in relation to its capacity must not exceed this threshold to be able to reach goods in compartment A. The threshold must be set if there is a maximum quantity scenario for the corresponding vehicle with the compartment setup ACCESS_A_THROUGH_B.
loadThresholdToAccessBThroughA Percent (Double) no - 2.29 Provided that compartment B can only be accessed through compartment A, the load in compartment A in relation to its capacity must not exceed this threshold to be able to reach goods in compartment B. The threshold must be set if there is a maximum quantity scenario for the corresponding vehicle with the compartment setup ACCESS_B_THROUGH_A.

CompartmentQuantityIndices

used by PlanToursOptions
since 2.29

A vehicle can have two special compartments, called compartments A and B in the following, where one compartment can only be accessed through the other compartment. Depending on the compartment setup of a maximum quantity scenario of the vehicle, compartment A can only be accessed through compartment B or the other way around. Each compartment is specified by an index that refers to the quantities of the maximum quantity scenarios and the transport orders. Specifying the compartment quantity indices is mandatory if a compartment access restriction is defined for a vehicle. See the technical concept page for details on the compartment access restriction.

Field Name Type Required Default Since Description
compartmentA Index (int) yes - 2.29 The quantity at the specified index refers to compartment A.
compartmentB Index (int) yes - 2.29 The quantity at the specified index refers to compartment B.

CostReport

used by TourReport, ToursResponse, TripReport
since 2.1

Cost related information describing tours or trips. The cost report contains accumulated values describing its parent object, which is either a tour response, a tour report or a trip report.

Field Name Type Required Default Since Description
travelTime Duration (double) yes - 2.1 The total duration between start and end of the described object. The travelTime contains all waiting, service, driving, break and rest times.
drivingTime Duration (double) yes - 2.1 The total driving time, which is the sum of the length of all driving events. The driving time of an empty ride might not belong to any trip. See Tours and Trips.
serviceTime Duration (Double) no - 2.9 The total service time, which is the sum of the length of all service events.
distance Distance (double) yes - 2.1 The total driven distance.
monetaryCostsReport MonetaryCostsReport no - 2.28 The costs calculated on the basis of the monetary cost options of the vehicle(s). For the monetary costs report of a trip report or a tour report or a tours response, the costs are in regards to the trip or the tour or the whole plan, respectively.

CustomerSite

extends Site
since 2.1

A specific site representing a customer location.

Field Name Type Required Default Since Description
customerId String no - 2.8 ID of the customer that can be set to link several customer sites with different opening intervals. Customer sites with the same customer ID may only differ in the location ID and in the opening intervals. Otherwise an exception is thrown. If successive stops at customer sites share the same customer ID, the service time per stop of the site and of the vehicle are only considered at the first stop of the sequence.
positionInTrip PositionInTrip no - 2.23

If specified, this stop has to be the very first/last customer stop in its trip whenever there is a stop at this customer site.
In each trip, there can only be one stop at a customer site with a trip section of type FIRST_CUSTOMER_STOP/LAST_CUSTOMER_STOP.
If specified, tripSectionNumber must not be set for the same customer site.
See technical concept Trip Sections and Positions in Trips for further details.

tripSectionNumber PositiveInteger (Integer) no - 2.23

If tripSectionNumber is specified, a stop at this customer site will be visited
after stops (within the same trip) at customer sites with specified lower tripSectionNumber and
before stops (within the same trip) at customer sites with specified higher tripSectionNumber.
Consequently, the trip section numbers of stops at customer sites will be non-decreasing within each trip.
If specified, positionInTrip must not be set for the same customer site.
See technical concept Trip Sections and Positions in Trips for further details.

DepotSite

extends Site
since 2.1

A specific site representing a depot. Depots act as trip delimiters. See Tours and Trips.

Field Name Type Required Default Since Description
additionalServiceTimePerPickupStop Duration (Double) no 0.0 2.26 Another site-dependent service time that is added to the general service time per stop of site if goods are picked up from the depot site. See Service time calculation.
additionalServiceTimePerDeliveryStop Duration (Double) no 0.0 2.26 Another site-dependent service time that is added to the general service time per stop of site if goods are delivered at the depot site. See Service time calculation.
serviceTimeFactorForOrders ServiceTimeFactor (Double) no 1.0 2.33 A factor that is multiplied with the service times of all orders' tasks carried out at this depot site, for example if loading/unloading is more or less complicated than for other depot sites. A factor less than 1.0 means that the depot site speeds up the service, a factor greater than 1.0 means that it slows the service down. See Service time calculation.

Driver

used by Fleet
since 2.7

A driver is always assigned to a specific vehicle instance and may not always be available to operate it. To be precise, a driver can only operate the corresponding vehicle instance within given time intervals. In addition, it may be specified how long the driver has already worked.

Field Name Type Required Default Since Description
id String yes - 2.7 ID of the driver.
operatingIntervals Interval[] 0..30 - 2.7 Interval during which the driver is available. The intervals must have a gap of more than 1 second. Each trip must lie completely within one of the operating intervals. The driving time outside trips must also lie completely within one of the operating intervals except for rest positions ANYWHERE chosen. The tour start and trip start events must lie within one of the operating intervals. Leaving this parameter empty means that the driver is always available. If multiple operating intervals are used for at least one driver, no time dependent distance matrix and no evaluateToursInExecution request may be used. If any operating interval contains a GDF time domain, a planning horizon is required.
breakIntervals BreakInterval[] 0..30 - 2.19 List of intervals within which the driver wants or needs to take a break. Intervals must be pairwise disjoint. The list must be empty if working hours are set. If any break interval contains a GDF time domain, a planning horizon is required.
vehicleId String yes - 2.7 ID of the driver's vehicle.
configurableWorkingHours ConfigurableWorkingHours no - 2.27 Defines configurable rules regarding drivers' working hours. This value may only be set if working hours are not set as a tour restriction, that is, globally. For the time being, the configurable working hours have to be the same for all drivers. Not supported for time-dependent driving times.
configurableWorkingHoursPreset ConfigurableWorkingHoursPreset no - 2.27 For the user's convenience, a preset can be chosen for the configurable working hours. Every preset stands for a pre-defined parameterization of the included rules and total time limits. Using a preset means that conversely, the configurable working hours must not be set additionally. This value may only be set if working hours are not set as a tour restriction, that is, globally. For the time being, the configurable working hours preset has to be the same for all drivers. Not supported for time-dependent driving times.
workLogbookSummary WorkLogbookSummary no - 2.16 The summary of a logbook of a driver. If such a summary is missing, it is assumed that the driver is fully rested.

EstimateByReferenceMatrix

extends DistanceMode
since 2.5

If not all route locations are part of the existing distance matrix, this distance mode can be used to indicate reference locations for each location. The distance matrix has to contain every reference location that is necessary for tour planning, otherwise an exception is thrown. For example, the distance matrix can be calculated by a createDistanceMatrix request.

Field Name Type Required Default Since Description
id String yes - 2.5 The unique identifier of an existing distance matrix that contains every reference location of the reference location mappings. The ID is generated when the distance matrix is created. It is checked case sensitively.
referenceLocationMappings ReferenceLocationMapping[] 1..* - 2.5 Maps each request location to a reference location. If any request location is not part of this mapping or if any reference location is not part of the distance matrix or if the keys of this mapping are not unique, an exception is thrown. A location's route location and its referenceLocation may be equal. Different locations may be mapped to the same reference location. Locations with the same route location may be mapped to different reference locations.

ExecutionState

used by ToursInExecutionRequest
since 2.21

The current state of a tour in execution. The work logbook summary specified at the driver of the given vehicle is overridden.

Field Name Type Required Default Since Description
vehicleId String yes - 2.21 Vehicle ID of the tour that is currently in execution. Note that the stored profile of the ToursInExecutionRequest is used for recomputation.
vehiclePosition VehiclePosition yes - 2.21 Position of the driver and his vehicle in a tour in execution.
currentTime XMLGregorianCalendar yes - 2.21 Current time of the execution state. It is assumed that the time between lastTimeTheDriverWorked of workLogbookSummary and currentTime counts as break/rest, provided it has the required minimum duration.
workLogbookSummary WorkLogbookSummary no - 2.21 The summary of a logbook of a driver. If such a summary is missing, it is assumed that the driver is fully rested.

ExistingDistanceMatrixPerVehicle

extends DistanceMode
since 2.8

Use an existing distance matrix per vehicle, for example from a createDistanceMatrix request. For distance mode ExistingDistanceMatrixPerVehicle, each vehicle has to have its own distance matrix ID set. If a vehicle does not have any distance matrix ID, an exception is thrown.

No fields defined.

FindChangeToursProposalsRequest

extends RequestBase
used by XTour
since 2.14

The request object for the service method proposeChangeToursActions.

Field Name Type Required Default Since Description
proposalsQuery ChangeToursProposalsQuery yes - 2.14 A query that defines which ChangeToursActions to propose.
proposalsOptions ChangeToursProposalsOptions no - 2.14 Contains options for the find change tours proposals use case.

Fixation

used by AddFixationsAction, InputPlan, RemoveFixationsAction
since 2.1

Different kinds of fixations that are considered during planning as additional restrictions.

Field Name Type Required Default Since Description
id String yes - 2.1 ID of the object that should be fixed. The type of object and the characterization of the fixation depends on the fixation type.
fixationType FixationType yes - 2.1 Different kinds of fixations.

Fleet

used by PlanToursRequest
since 2.1

A fleet consisting of vehicles that are available to transport goods or perform visits.

Field Name Type Required Default Since Description
vehicles Vehicle[] 1..* - 2.1 A list of vehicles that can be used to transport goods or perform visits.
drivers Driver[] 0..* - 2.7 A list of drivers. Vehicles without associated driver have no restrictions concerning driver operating intervals. All tour restrictions must be fulfilled by both vehicles with and without associated driver.

InputPlan

used by PlanToursRequest
since 2.1

A list of tours that serves the algorithm as start solution (e.g. tours of previous responses). All tours of an input plan have to be structurally valid. See Tours and Trips for a description of valid tour structures. The input tours can generally be changed or dissolved except when they are fixed. Violated input tours cannot be changed and appear unchanged in the response with their tour events containing tour violations.

Field Name Type Required Default Since Description
tours Tour[] 1..* - 2.1 List of input tours.
fixations Fixation[] 0..* - 2.1 Fixations of input tours.
tripStartIntervals TripStartInterval[] 0..* - 2.19 If a trip start interval is set for a trip in a planToursRequest, a fixation of type trip to vehicle has to be explicitly set for this trip. It is possible however to remove the fixation via a removeFixationsAction and to use all ChangeToursActions or findChangeToursProposalsRequests. A PlanToursRequest with calculation mode EVALUATE also does not need a fixation.

InsertionAfterSpecifiedPosition

extends InsertionPosition
since 2.5

This type defines the insertion position of a task, stop or trip after a specified position.

Field Name Type Required Default Since Description
position Index (int) yes - 2.5 Position to insert the task or trip after. The specified position is associated with a stop in a trip if this object is used in a MoveOrdersAction or MoveStopsAction. The specified position is associated with a trip in a tour if this object is used in a MoveTripsAction or a AddTripAction.

InsertionAtBestPosition

extends InsertionPosition
since 2.8

This type defines the insertion position of a task, stop or trip at the best position. If no valid position can be found, the IDs of the respective orders are added to orderIdsNotPlanned after performing the ChangeToursAction.

No fields defined.

InsertionBeforeSpecifiedPosition

extends InsertionPosition
since 2.5

This type defines the insertion position of a task, stop or trip before a specified position.

Field Name Type Required Default Since Description
position Index (int) yes - 2.5 Position to insert the task or trip before. The specified position is associated with a stop in a trip if this object is used in a MoveOrdersAction or MoveStopsAction. The specified position is associated with a trip in a tour if this object is used in a MoveTripsAction or a AddTripAction.

InsertionIntoEmptyTour

extends InsertionPosition
since 2.5

This type defines the insertion position of a trip into an empty tour. It can be used in a MoveTripsAction to move a trip to an empty vehicle or by a AddTripAction to create a trip for an empty vehicle.

No fields defined.

The abstract base type to define the insertion position of a task, stop or trip.

No fields defined.

InsertionPositionsForOrdersQuery

extends ChangeToursProposalsQuery
since 2.26

A query to propose insertion positions for unplanned orders. Only structurally valid positions are proposed, for details please have a look at tour structures. The proposed change tours actions are either add trip actions or move orders actions. If violated insertion positions shall be part of the proposals, set returnViolatedTours to true. The resulting tour is contained in the Tours and TourReports. This query may be used to analyze unscheduled orders, see the corresponding integration sample.

Field Name Type Required Default Since Description
orderIds String[] 1..1 - 2.26 IDs of the orders to be inserted. All referenced orders need to be unplanned, otherwise an OrderAlreadyPlannedFault is thrown. At the moment, only one order is supported.
targetVehicleIds String[] 0..* - 2.26 Option to restrict target vehicles. If empty, all vehicles of different types of the plan are considered as target vehicles.
maximumNumberOfMoveOrdersActions NonNegativeInteger (Integer) no 100 2.26 Option to restrict the number of proposals which may reduce the calculation time of the request. At most the given number of MoveOrdersActions are proposed.
maximumDistanceOfAdjacentStops Distance (Double) no - 2.26 Option to restrict the number of proposals which may reduce the calculation time of the request. A MoveOrdersAction is proposed only if the airline distance of the leg between the sites of the given order and the adjacent stops in the tour is less than the given value.

LegReport

used by TourReport
since 2.15

Contains information for the route between two successive sites of a tour. A leg is either between two stops of a trip, between two trips, between the vehicle start location and the first stop of the tour or between the last stop of a tour and the vehicle end location. For further information please have a look at the technical concept Tours and Trips.

Field Name Type Required Default Since Description
startTourEventIndex Index (Integer) no - 2.15 References the first driving event of this leg.
endTourEventIndex Index (Integer) no - 2.15 References the last driving event of this leg.
drivingTime Duration (Double) no - 2.15 The driving time between start and end location.
distance Distance (Double) no - 2.15 The driven distance between start and end location.
estimatedByDirectDistance Boolean no - 2.15 True if the driving time of this leg is estimated by direct distance instead of the road network.

Possible causes:

  • start or end not within boundaries of map,
  • start or end too far from next road,
  • no route found between start and end.

If EstimateByReferenceMatrix is used as distance mode, the leg is estimated by direct distance if and only if the according reference locations are estimated by direct distance. If DirectDistance is used as distance mode, this flag will always be set.
routeViolated Boolean no - 2.15 True if the leg is calculated with route violations. If EstimateByReferenceMatrix is used as distance mode, the route is violated if and only if the route between the according reference locations is violated.
transportQuantities TransportQuantityUnit[] (Double[]) 0..100 - 2.15 Current load on the vehicle when driving between the two successive stops.
maximumQuantityScenarioIndex Index (Integer) no - 2.26 Index of the used maximum quantity scenario of the vehicle. If the tour is violated, always index 0 is chosen. The quantity scenario is changed as late as possible given the allowed quantity scenario change position.

Location (abstract)

extended by Site, VehicleLocation
used by PlanToursRequest
since 2.1

The abstract base type for all kinds of locations. See Orders, Locations, and Stops.

Field Name Type Required Default Since Description
id String yes - 2.1 A unique ID for this location. This ID can be used to reference the location from other elements, for example from orders or vehicles. For multiple identical PlanToursRequests the PlanToursResponse will always be the same. But please be aware that different IDs can lead to different results.
routeLocation RouteLocation yes - 2.1 The exact map coordinate of this location.

MaximumQuantityScenario

used by Vehicle
since 2.1

A scenario for the maximum quantities of goods of different kind.

Field Name Type Required Default Since Description
quantities TransportQuantityUnit[] (Double[]) 1..100 - 2.1 List of capacities for the different quantity dimensions of goods that can be transported. The maximum length of this list is 100. That is, up to 100 different quantity dimensions (e.g. number of pallets, weight, volume, etc.) can be distinguished. Transport orders can only be transported by a vehicle with a higher (or an equal) maximum quantity in every quantity dimension of at least one quantity scenario. The length of this list has to be the same for all transport orders and all maximum quantity scenarios of all vehicles.
compartmentSetup CompartmentSetup no - 2.29 This compartment setup must be specified if and only if the compartment access restriction is used for the corresponding vehicle. The compartment setup tells whether the compartment A can only be accessed by walking through compartment B or the other way around. Compartments A and B are defined by the compartment quantity indices.

MixedLoadingProhibition

used by MixedLoadingProhibitionsViolation, TourRestrictions, ViolationReport
since 2.25

There may be some orders that shall not be mixed with some other orders on one trip. For instance, it may be prohibited to load certain dangerous goods together on the same trip, such as flammable solids on the one hand and explosive substances on the other hand. A mixed loading prohibition is a pair of two conflicting categories that prohibits orders of these categories to be mixed on the same trip. The category can be specified for every order. For a vehicle, there is a flag that lets the vehicle ignore this restriction.

Field Name Type Required Default Since Description
conflictingCategory1 String yes - 2.25 An order of this category is not allowed to be on the same trip as an order of the other category. The category can be any string but it must not be empty and not the same as the other conflicting category.
conflictingCategory2 String yes - 2.25 An order of this category is not allowed to be on the same trip as an order of the other category. The category can be any string but it must not be empty and not the same as the other conflicting category.

MonetaryCostOptions

used by Vehicle
since 2.28

Specifies options for calculating monetary costs for a vehicle. Cost totals are output in the cost reports of the response.

Field Name Type Required Default Since Description
travelTimeCostPerHour NonNegativeDouble (Double) no 0.0 2.28 Monetary cost per hour of travel time (comprises driving time, service time and idle time). The currency unit is implicit and assumed to be the same for all fields.
distanceCostPerKilometer NonNegativeDouble (Double) no 0.0 2.28 Monetary cost per kilometer of driven distance. The currency unit is implicit and assumed to be the same for all fields.
fixedCostPerTour NonNegativeDouble (Double) no 0.0 2.28 Monetary cost for using the vehicle (or one of the vehicles if multiple ids are given). The currency unit is implicit and assumed to be the same for all fields.

MonetaryCostsReport

used by CostReport
since 2.28

Contains the costs calculated on the basis of the monetary cost options of the vehicle(s). The implicit currency unit of the cost values is the same as for the monetary cost options of the vehicles. A monetary costs report may refer to a trip, a tour or the whole plan.

Field Name Type Required Default Since Description
totalCost NonNegativeDouble (double) yes - 2.28 The sum of the other monetary costs in this report.
travelTimeCost NonNegativeDouble (double) yes - 2.28 The travel time cost calculated on the basis of the travel time cost factor(s) of the vehicle(s).
distanceCost NonNegativeDouble (double) yes - 2.28 The distance cost calculated on the basis of the distance cost factor(s) of the vehicle(s).
fixedCost NonNegativeDouble (double) yes - 2.28 The fixed cost calculated on the basis of the fixed cost factor(s) of the vehicle(s).

MoveOrdersAction

extends ChangeToursAction
since 2.5

A specific action to move orders from unplanned orders or existing trips to an existing trip. Currently, a MoveOrdersAction cannot both contain visit and transport orders. If multiple orders of a stop shall be moved, use a MoveStopsAction. All specified insertion positions refer to the trip before performing this MoveOrdersAction.

The following conditions must be fulfilled or an exception will be thrown:

  • If any order referenced by orderIds is a visit order, visitInsertionPosition must be set.
  • If any order referenced by orderIds is a transport order, pickupInsertionPosition and deliveryInsertionPosition must be set.
  • Unless the task's insertion position is of type insertion at best position, every task must have the same site unless the site is
    • equal to the site of the stop directly before the insertion position, or
    • equal to the site of the stop directly after the insertion position.

In case of moving an order of type OrderWithAlternativePickupDepots or OrderWithAlternativeDeliveryDepots the depot of the order can change if it is better to serve the order at a different depot.

Field Name Type Required Default Since Description
orderIds String[] 1..* - 2.5 IDs of the orders to be moved.
targetTripId String yes - 2.5 ID of the trip to insert the orders into.
visitInsertionPosition InsertionPosition no - 2.5 Insertion position for visit orders. Currently this should be set if and only if all referenced orders in orderIds are visit orders.
pickupInsertionPosition InsertionPosition no - 2.5 Insertion position for pickup tasks of transport orders. Currently this should be set if and only if all referenced orders in orderIds are transport orders.
deliveryInsertionPosition InsertionPosition no - 2.5 Insertion position for delivery tasks of transport orders. Currently this should be set if and only if all referenced orders in orderIds are transport orders.

MoveStopsAction

extends ChangeToursAction
since 2.5

A specific action to move consecutive stops from an existing trip to another existing trip. The stops may be moved within their original trip or to another trip. If the stops are moved to another trip, all partner tasks of tasks of the moved stops will be moved too. The insertion positions of the partner tasks in the target tour are implicitly defined. They are inserted at the closest existing stop at the according location or a new start/end depot is created. A new start/end depot may only be created if it is unambiguous, i.e. there is no other start/end depot already. For all other partner tasks, it is necessary that all their locations are already in the target trip. If the insertion position of the partner task is ambiguous, an AmbiguousInsertionPositionFault is thrown. If the stops are moved within their original trip, the partner tasks stay at their old position.

In case of moving stops that contain orders of type OrderWithAlternativePickupDepots or OrderWithAlternativeDeliveryDepots the depot of the order can change if it is better to serve the order at a different depot.

Field Name Type Required Default Since Description
stopIdentifiers StopIdentifier[] 1..* - 2.5 Defines the stops to be moved.
targetTripId String yes - 2.5 ID of the trip to insert the stop into.
insertionPosition InsertionPosition yes - 2.5 Insertion position of the stop in the trip. InsertionAtBestPosition is not supported for this ChangeToursAction yet and its usage causes an exception.

MoveTripsAction

extends ChangeToursAction
since 2.5

A specific action to move a trip to a specified position in an existing tour or to an empty vehicle. The trip may be moved within its original tour or to another tour. For certain special tour structures moving a trip could cause adjacent trips to become one trip. Such MoveTripsActions are currently not supported and throw an exception.

In case of moving a trip that contains orders of type OrderWithAlternativePickupDepots or OrderWithAlternativeDeliveryDepots the depot of the order can change if it is better to serve the order at a different depot.

Field Name Type Required Default Since Description
tripIds String[] 1..1 - 2.5 IDs of the trips to be moved. At the moment, only one trip is supported.
targetVehicleId String yes - 2.5 ID of the vehicle corresponding to the tour to insert the trip into or ID of an unused vehicle to move the trip onto. At the moment, only one trip is supported.
insertionPosition InsertionPosition yes - 2.5 Insertion position of the trip in the tour. If InsertionPosition is of type InsertionAtBestPosition, a trip is only moved if the target vehicle is different from the vehicle that currently serves the trip. Trips in tripIds that can not be moved to the target vehicle are not changed and are listed in a NoValidInsertionPositionFoundLimitation as objectIds.

NoValidInsertionPositionsFoundLimitation

extends ResultLimitation
since 2.16

This result limitation indicates that a request could not be properly moved for the objects listed in objectIds because no valid position was found.

Field Name Type Required Default Since Description
objectIds String[] 0..* - 2.16 IDs of the objects that could not be moved to a valid position.

The object type depends on the action type of the ChangeToursRequest:

OptimizeStopSequenceAction

extends ChangeToursAction
since 2.8

A specific action to optimize the stop sequence of trips. Keep in mind that the optimization goal is to minimize the travel and driving time of the overall tour.

Field Name Type Required Default Since Description
tripIds String[] 1..* - 2.8 IDs of the trips to be optimized concerning their stop sequence.

Order (abstract)

extended by TransportOrder, VisitOrder
used by PlanToursRequest
since 2.1

Base type for orders that should be carried out in the tours. See Orders, Locations, and Stops.

Field Name Type Required Default Since Description
id String yes - 2.1 An unique ID used to identify the order. For multiple identical PlanToursRequests the PlanToursResponse will always be the same. But please be aware that different IDs can lead to different results.
priority OrderPriority (Integer) no - 2.25 Priority of this order. 0 is the lowest priority, 9 the highest. This field is only considered during automatic planning if considerOrderPriorities is set. In this case every order must have an order priority set otherwise an exception is thrown - if considerOrderPriorities is set to false either every or no order may have a priority set. If the algorithm can plan all orders during automatic planning this field does not affect the result. Otherwise the algorithm considers the priorities according to the following rule: If an order cannot be planned without removing an order with higher priority, it will remain unplanned. Please keep in mind that using multiple priorities will increase the computation time of the algorithm. See technical concept Order Priorities for further details.
groupId String no - 2.13 The unique identifier of an order group. The preferences that apply to orders with the same group ID are specified in the order group consideration. Order groups may be referenced in the order group IDs of a vehicle. See technical concept Order Groups for further details.
requiredVehicleEquipment String[] 0..* - 2.3 List of required vehicle equipment. A vehicle can only be assigned to the order if this list is a subset of (or equal to) the vehicle's equipment.
category String no - 2.25 Category of an order. To specify a category is useful if there are orders of one category that shall not be mixed with orders of another category on one trip. If two categories are mutually exclusive on a trip, this can be specified as a mixed loading prohibition. Orders of conflicting categories will not be planned together on one trip.

OrderGroupConsideration

used by PlanToursOptions
since 2.13

Defines strong preferences concerning order groups. They are considered in automatic planning. If these preferences are not met for an input plan or for a change tours action, they are not reported as a violation. For further information please have a look at the technical concept Order Groups. Currently, oneTripPerGroup can only be activated if oneGroupPerTrip is also activated, otherwise an exception is thrown.

Field Name Type Required Default Since Description
oneGroupPerTrip Boolean no false 2.13 If set to true, orders of a specific group cannot be planned together with orders of another group into a trip and orders without groupIds remain unplanned.
oneTripPerGroup Boolean no false 2.13 If set to true, orders of a specific group must be planned together in one trip.

OrderWithAlternativeDeliveryDepots

extends TransportOrder
since 2.13

A specific transport order that allows the goods to be delivered to alternative depot sites.

Field Name Type Required Default Since Description
pickupLocationId String yes - 2.13 ID of the location where the goods should be picked up. Only a customer site is allowed as pickup location.
deliveryLocationIds String[] 0..* - 2.13 IDs of alternative depot sites where the goods should be delivered to. All delivery depots are treated equally and only one of the depots is chosen for the resulting tour. If the list is empty, all depots are considered as possible delivery locations.

OrderWithAlternativePickupDepots

extends TransportOrder
since 2.13

A specific transport order that allows the goods to be picked up at alternative depot sites.

Field Name Type Required Default Since Description
pickupLocationIds String[] 0..* - 2.13 IDs of alternative depot sites where the goods should be picked up. All pickup depots are treated equally and only one of the depots is chosen for the resulting tour. If the list is empty, all depots are considered as possible pickup locations.
deliveryLocationId String yes - 2.13 ID of the location where the goods should be delivered to. Only a customer site is allowed as delivery location.

PickupDeliveryOrder

extends TransportOrder
since 2.1

A specific transport order that allows the goods to be picked up at one location and be delivered to a different location.

Field Name Type Required Default Since Description
pickupLocationId String yes - 2.1 ID of the location where the goods should be picked up. This location is either a customer site or a depot site.
deliveryLocationId String yes - 2.1 ID of the location where the goods should be delivered to. This location is either a customer site or a depot site.

PlanToursOptions

used by PlanToursRequest
since 2.1

Contains global planning settings.

Field Name Type Required Default Since Description
planningHorizon StartEndInterval no - 2.3 Defines the planning horizon for this request, described by start and end date. It restricts all tours which means their beginning and end need to be in this planning horizon. All opening intervals outside of this planning horizon are not considered during the tour planning process. If the opening intervals, driver operating intervals or break intervals contain GDF time domains, the planning horizon is a required parameter to limit the number of recurring intervals of the time domains. The planning horizon is restricted to a maximum duration of two weeks.
restrictions TourRestrictions no - 2.1 Defines restrictions for the planning algorithm.
calculationMode CalculationMode no CalculationMode.S ... 2.1 Defines the calculation mode of the planning algorithm.
customCalculationModeConfiguration EncodedContent (String) no - 2.16 Defines a specific configuration for calculation mode CUSTOM in an encoded form.
tweaksToObjective TweaksToObjective no - 2.23 Defines specific tweaks to the objective of the algorithm.
enableMonetaryCostMinimization Boolean no false 2.28 This field is deprecated and enabling it leads to an exception.
enableOptimizationPremium Boolean no false 2.28 Optimization Premium delivers higher quality solutions by exploring larger set of diverse neighborhoods, which are only available within this mode. The improvement from Optimization Premium can be obtained using all calculation modes. The running time of Optimization Premium can be higher compared to the standard algorithm without Optimization Premium. Optimiziation Premium requires a special license, make sure you understand the implications of Optimization Premium. See technical concept Optimization Premium for further details.
orderGroupConsideration OrderGroupConsideration no - 2.13 Defines strong preferences concerning order groups. They are considered in automatic planning. If these preferences are not met for an input plan or for a change tours action, they are not reported as a violation.
singleStopPerCustomerSite Boolean no false 2.18 Defines a strong preference that all tasks of orders for the same customer site are carried out at the same stop if possible. If this is not possible, all unplanned orders for that customer site remain unplanned. Transport orders between two customer sites are ignored here. This preference is only considered in automatic planning. If this preference is not met for an input plan or for a change tours action, it is not reported as a violation.
considerOrderPriorities Boolean no false 2.25 If set to true order priorities are considered during automatic planning. Please keep in mind that using multiple priorities will increase the computation time of the algorithm. See technical concept Order Priorities for further details.
ignoreRouteViolations Boolean no true 2.25 If this field is set to true, route violations are ignored. No route violation is reported at the tour events. If this field is set to false, automatic planning will not create a tour with a route violation. Input tours with a route violation will be treated as violated tours and therefore will not be changed by the automatic planning. At the leg report and at the tours response route violated is set regardless of this field.
ignoreReachabilityViolations Boolean no true 2.25 If this field is set to true, reachability violations are ignored. No reachability violation is reported at the tour events. If this field is set to false, automatic planning will not create a tour with a reachability violation. Input tours with a reachability violation will be treated as violated tours and therefore will not be changed by the automatic planning. At the leg report estimated by direct distance is set regardless of this field.
compartmentQuantityIndices CompartmentQuantityIndices no - 2.29 A vehicle can have two special compartments, where one compartment can only be accessed through the other compartment. The compartments are defined by their quantity indices. These quantity indices must be specified if the compartment access restriction is used for a vehicle (and are irrelevant otherwise). See the technical concept page for details on the compartment access restriction.

The request object for the service method planTours.

Field Name Type Required Default Since Description
locations Location[] 1..* - 2.1 A list of vehicle locations, depot sites or customer sites that should be served or visited.
orders Order[] 1..* - 2.1 A list of orders that should be planned into tours.
fleet Fleet yes - 2.1 The fleet that should be used to conduct the planned tours.
inputPlan InputPlan no - 2.1 A list of tours that serves the algorithm as start solution (e.g. tours of previous responses). The input tours can generally be changed or dissolved except when they are fixed. To evaluate an input plan without changing it, use calculation mode EVALUATE.
planToursOptions PlanToursOptions no - 2.1 Contains planning options.
distanceMode DistanceMode yes - 2.1 Contains settings that specify how distances are retrieved for tour planning. These settings apply to all vehicles in the request. When using direct distance the driven distances are estimated with a detour factor of 1.38 and for the duration a speed of 60 km/h is assumed. Time dependent and non time dependent distance matrices must not be used together in a request. If time dependent distance matrices are used, no driving time regulation must be set.
storeRequest Boolean no false 2.5 Defines if the request should be stored in the session storage. Note that if there occur problems with the session storage, an ObjectNotStoredLimitation is generated and the stored request ID in the response is null.

PositionAtStop

extends VehiclePosition
since 2.21

Driver and his vehicle are at a stop of the tour. If the trip with the given id starts at the given stop and the driver has arrived at the stop, then the corresponding TRIP_START event is returned in the tour events. If the trip with the given id ends at the given stop and the driver has completed his service, then the corresponding TRIP_END event is not returned and no trip report is created for this trip.

Field Name Type Required Default Since Description
serviceStatus ServiceStatus yes - 2.21 Specifies if service has not started yet, service is currently being performed or if service is completed.
tripId String yes - 2.21 Trip ID of the current stop.
stopIndex Index (int) yes - 2.21 Zero based index of current stop in the tour. Counting of stops starts at the first stop of the specified trip.

PositionAtVehicleStartLocation

extends VehiclePosition
since 2.21

Position of the driver and his vehicle is still at the start of the tour.

No fields defined.

PositionEnRouteToStop

extends VehiclePosition
since 2.21

Driver and his vehicle are currently en route between stops or between the vehicle start location and the first stop of the first trip. PositionEnRouteToStop may not be used before the first stop of the first trip if the tour does not start before this stop. An exception is thrown otherwise.

Field Name Type Required Default Since Description
currentLocation Coordinate yes - 2.21 Current geographic location of driver and his vehicle.
tripId String yes - 2.21 Trip ID of the the next stop.
indexOfNextStop Index (int) yes - 2.21 Zero based index of next stop in the trip. Counting of stops starts at the first stop of the specified trip.

PositionEnRouteToVehicleEndLocation

extends VehiclePosition
since 2.21

Driver and his vehicle are currently en route between the last stop of the tour and the vehicle end location. PositionEnRouteToVehicleEndLocation may not be used after the last stop of the last trip if the tour ends at this stop. An exception is thrown otherwise.

Field Name Type Required Default Since Description
currentLocation Coordinate yes - 2.21 Current geographic location of driver and his vehicle.

ReferenceLocationMapping

used by EstimateByReferenceMatrix
since 2.5

A mapping of a location that is part of the request to a route location. The route location is used as a reference, e.g. for distance calculation.

Field Name Type Required Default Since Description
locationId String yes - 2.5 The unique identifier of a location that is part of the request. It is checked case sensitively.
referenceLocation RouteLocation yes - 2.5 The route location that is used as a reference for the location in a distance matrix. It may be equal to the location's route location.

RemoveFixationsAction

extends ChangeToursAction
since 2.7

A specific action to remove fixations from the current plan. If at least one of the fixations references the ID of a nonexistent object, an exception is thrown and none of the fixations are removed. If one of the fixations is not in the current plan, no exception is thrown but the fixation is just ignored. If one of the fixations exists in the current plan multiple times, all occurences will be removed. However we do not distinguish between one or multiple occurences of a fixation.

Field Name Type Required Default Since Description
fixations Fixation[] 1..* - 2.7 Fixations to be removed from the current plan.

RemoveOrdersAction

extends ChangeToursAction
since 2.5

A specific action to remove orders from the current plan. If removing the orders leads to an empty trip with a trip start interval, the trip start interval is also removed from the input plan.

Field Name Type Required Default Since Description
orderIds String[] 1..* - 2.5 IDs of the orders to be removed.

RemoveToursAction

extends ChangeToursAction
since 2.5

A specific action to remove tours from the current plan. For each removed tour that contained a trip with a trip start interval, the trip start interval is also removed from the input plan.

Field Name Type Required Default Since Description
vehicleIds String[] 1..* - 2.5 IDs of the vehicles of the tours to be removed.

RemoveTripStartIntervalsAction

extends ChangeToursAction
since 2.19

A specific action to remove trip start intervals from the current plan. If at least one of the trip IDs references the ID of a nonexistent trip, an exception is thrown and none of the trip start intervals are removed. If for one of the trip ids no trip start interval is specified in the current plan, no exception is thrown but the trip ID is just ignored.

Field Name Type Required Default Since Description
tripIds String[] 1..* - 2.19 TripStartIntervals to be removed from the current plan.

RemoveTripsAction

extends ChangeToursAction
since 2.5

A specific action to remove trips from the current plan. For each removed trip with a specified trip start interval, the trip start interval is also removed from the input plan.

Field Name Type Required Default Since Description
tripIds String[] 1..* - 2.5 IDs of the trips to be removed.

Site (abstract)

extends Location
extended by CustomerSite, DepotSite
since 2.1

A specific location where goods can be picked up or delivered. This location is either a depot or a customer location. It is highly recommended to avoid multiple sites with the same members to improve performance and solution quality!

Field Name Type Required Default Since Description
openingIntervals Interval[] 0..30 - 2.1 Opening intervals for this site, specified in one of the valid interval formats. Leaving this parameter empty means that the site is always open. Service can only start within one of the opening intervals. If a planning horizon is defined for the request, all opening intervals outside of this horizon are not considered during the tour planning process. If this list of intervals contains GDF time domains, a planning horizon is required. If no planning horizon is defined, it is required that the opening intervals of all sites do not span a horizon longer than two weeks.
serviceTimePerStop Duration (Double) no 0.0 2.1 Site dependent service time, for example to enter an area or to register at a customer. This service time will be considered for each stop that is performed at this site. If additional service time per pickup stop or additional service time per delivery stop is defined at a depot, this value is added to the stop service time. Additionally there may be an order dependent or vehicle dependent service time of the stop. See Service time calculation.
ignoreVehicleDependentServiceTimeFactorForOrders Boolean no false 2.1 Indicates if vehicle dependent service time factors are relevant for this site, for example if the vehicle is unloaded by ramp staff. If this parameter is set to true, no vehicle dependent service times are taken into account for this site. See Service time calculation.

Stop

used by Trip
since 2.1

A stop groups subsequent tasks of a tour that are carried out at the same site. If there is more than one task at the same customer site, tasks are grouped to one stop and scheduled in order of their type: DELIVERY tasks before VISIT tasks before PICKUP tasks. If there is more than one task at the same depot site, all DELIVERY tasks are grouped to one stop and all PICKUP tasks are grouped to another one. See Orders, Locations, and Stops.

Field Name Type Required Default Since Description
locationId String yes - 2.1 The reference to the location of the site where the stop is served. This location is either a customer site or a depot site.
customerId String no - 2.8 ID corresponding to the customerId of a customer site. This parameter needs to be set if the locationId of the stop belongs to a customer site with defined customer ID. Else, the parameter must not be set.
tasks Task[] 1..* - 2.1 A list of tasks, each being part of an order, that are carried out at the referenced site.

StopIdentifier

used by MoveStopsAction
since 2.5

Identifies a stop by a trip ID and a position.

Field Name Type Required Default Since Description
tripId String yes - 2.5 ID of the trip that contains the stop.
position Index (int) yes - 2.5 Position of stop within trip.

Task

used by Stop
since 2.1

Each task of an order is carried out at a stop of a tour.

Field Name Type Required Default Since Description
orderId String yes - 2.1 The reference to the order of this task.
taskType TaskType yes - 2.1 Type of task that is carried out, for example picking up an order.

Tour

used by ChangeToursProposal, InputPlan, ToursResponse
since 2.1

As an operation schedule for a single vehicle, a tour provides the information which tasks are carried out in which order by the specified vehicle respectively its driver. There is at most one tour per vehicle. A tour contains a sequence of trips. See Tours and Trips.

Field Name Type Required Default Since Description
vehicleId String yes - 2.1 The reference to the specific vehicle that is used to conduct this tour.
vehicleStartLocationId String no - 2.1 ID of this tour's vehicle's start location. This is always identical to the start location ID of the vehicle that is used to conduct this tour.
vehicleEndLocationId String no - 2.1 ID of this tour's vehicle's end location. This is always identical to the end location ID of the vehicle that is used to conduct this tour.
trips Trip[] 1..* - 2.1 A sequence of trips along this tour.

TourEvent

used by TourReport
since 2.1

Different kinds of events that can happen during execution of a tour.

Field Name Type Required Default Since Description
startTime XMLGregorianCalendar yes - 2.1 Start time of the event. The time zone is that of the planning horizon (if a planning horizon is defined) or that of a given location.
tripId String no - 2.1 ID of the trip this event is referring to, for example for a TRIP_START event. Not set for events that do not belong to a specific trip such as DRIVING events between depot sites of adjacent trips.
locationId String no - 2.1 ID of the location where the vehicle is stopped during this event. Not set for events that do not belong to a specific site such as DRIVING events or BREAK events that occur en route between two stops.
orderId String no - 2.1 ID of the order that is currently carried if the event is a SERVICE event. Not set for other event types.
eventTypes TourEventType[] 1..* - 2.1 Types of this event.
tourViolations TourViolation[] 0..* - 2.5 Violations of this event.
duration Duration (double) yes - 2.1 Duration of this event.

TourPlanProgress

extends JobProgress
since 2.1

The base type for any progress that is returned from the tour planning algorithm. Currently we do not provide any kind of progress for that.

No fields defined.

TourReport

used by ChangeToursProposal, ToursResponse
since 2.1

More detailed information about a tour, containing reports for each trip, an accumulated cost report and a list of events that occur along the tour.

Field Name Type Required Default Since Description
vehicleId String yes - 2.1 ID of vehicle of this tour.
costReport CostReport yes - 2.1 Cost related values for this tour.
violationReport TourViolationReport no - 2.5 Summary for tour violations of this tour.
tripReports TripReport[] 0..* - 2.1 Each element contains additional information about the trip with the corresponding ID.
tourEvents TourEvent[] 0..* - 2.1 Tour events for this tour. They are sorted by time and cover the whole period of the tour without gaps or overlaps. The time zone of the tour events is the time zone of the planning horizon (if a planning horizon is defined) or that of a given location.
legReports LegReport[] 0..* - 2.15 Contains information for the route between two successive stops of this tour.

TourRestrictions

used by PlanToursOptions
since 2.1

Restrictions that can be set for a tour.

Field Name Type Required Default Since Description
singleTripPerTour Boolean no false 2.1 Restricts the number of trips for each tour to one. See Tours and Trips.
singleDepotPerTour Boolean no false 2.1 Restricts the number of depots of a tour to at most one. That means a tour without depots is also valid if this parameter is set to true. See Tours and Trips.
maximumNumberOfCustomerStopsPerTour NonNegativeInteger (Integer) no - 2.24 Restricts the maximum allowed number of customer stops, i.e. stops at customer sites, per tour. If this parameter is set, maximum number of customer stops at vehicles must not be set, otherwise an exception is thrown. Is infinite if it is not set.
maximumDistancePerTour Distance (Double) no - 2.24 Restricts the maximum allowed total distance per tour in meters. If this parameter is set, maximum distance at vehicles must not be set, otherwise an exception is thrown. Is infinite if it is not set. This restriction is ignored for ToursInExecutionRequests.
maximumTravelTimePerTour Duration (Double) no - 2.5 Restricts the maximum allowed total travel time per tour in seconds. The travel time contains all waiting, service and driving times. Drivers' working hours may be more restrictive and enforce a lower limit. If this parameter is set, maximum travel time at vehicles must not be set, otherwise an exception is thrown. Is infinite if it is not set. This restriction is ignored for ToursInExecutionRequests.
maximumDrivingTimePerTour Duration (Double) no - 2.5 Restricts the maximum allowed total driving time per tour in seconds. Drivers' working hours may be more restrictive and enforce a lower limit. If this parameter is set, maximum driving time at vehicles must not be set, otherwise an exception is thrown. Is infinite if it is not set. Not supported for time-dependent driving times. This restriction is ignored for ToursInExecutionRequests.
workingHours WorkingHours no - 2.5 Defines the rules regarding drivers' working hours. Drivers' working hours are only active if this member is set.
mixedLoadingProhibitions MixedLoadingProhibition[] 0..* - 2.25 Defines restrictions regarding which categories of orders are disallowed to be mixed on the same trip.

TourViolationReport

extends ViolationReport
used by TourReport
since 2.5

Violation related information describing tours. The tour violation report contains violation summaries of its parent object, which is a tour report.

Field Name Type Required Default Since Description
planningHorizonExceedance Duration (Double) no - 2.7 The duration by which the start or the end of the planning horizon is exceeded. Corresponds to tour events with violation type PLANNING_HORIZON.
operatingIntervalExceedance Duration (Double) no - 2.7 The longest driver operating intervals exceedance. Corresponds to tour events with violation type OPERATING_INTERVAL.
tourStartIntervalExceedance Duration (Double) no - 2.19 The duration by which the end of the tour start interval is exceeded. Corresponds to tour events with violation type TOUR_START_INTERVAL.
maximumDrivingTimePerTourExceedance Duration (Double) no - 2.5 The duration by which the specified maximum driving time per tour is exceeded. (Either specified by an explicit value at maximum driving time of tour restrictions or maximum driving time of vehicle or by the drivers' working hours restriction). Corresponds to tour events with violation type MAXIMUM_DRIVING_TIME_PER_TOUR.
maximumTravelTimePerTourExceedance Duration (Double) no - 2.5 The duration by which the the specified maximum travel time per tour is exceeded. (Either specified by an explicit value at maximum travel time of tour restrictions or maximum travel time of vehicle or by the drivers' working hours restriction). Corresponds to tour events with violation type MAXIMUM_TRAVEL_TIME_PER_TOUR.
maximumDrivingTimePerDriverExceedance Duration (Double) no - 2.21 The duration by which the specified maximum driving time per driver is exceeded. Corresponds to tour events with violation type MAXIMUM_DRIVING_TIME_PER_DRIVER.
maximumTravelTimePerDriverExceedance Duration (Double) no - 2.21 The duration by which the specified maximum travel time per driver is exceeded. Corresponds to tour events with violation type MAXIMUM_TRAVEL_TIME_PER_DRIVER.
maximumTripStartIntervalExceedance Duration (Double) no - 2.19 The longest trip start interval exceedance. Corresponds to tour events with violation type TRIP_START_INTERVAL.
maximumNumberOfCustomerStopsExceedance PositiveInteger (Integer) no - 2.23 Number of stops by which the maximum number of customer stops per tour is exceeded. (Either specified by maximum number of customer stops of tour restrictions or maximum number of customer stops of vehicle) Corresponds to tour events with violation type MAXIMUM_NUMBER_OF_CUSTOMER_STOPS.
maximumDistanceExceedance Distance (Double) no - 2.24 The distance by which the the specified maximum distance per tour is exceeded. The limit is either specified by maximum distance of tour restrictions or maximum distance of vehicle. Corresponds to tour events with violation type MAXIMUM_DISTANCE.

ToursInExecutionRequest

extends RequestBase
used by XTour
since 2.21

The request object for the service method evaluateTours.

Field Name Type Required Default Since Description
storedRequestId String yes - 2.21 ID of the stored PlanToursRequest that contains all information about the tours as input plan. Currently, the list of break intervals must be empty for all drivers in the stored request and no driver may have more than one driver operating interval specified.
executionStates ExecutionState[] 1..* - 2.21 The current state for each tour in execution that gets recomputed by evaluteToursInExecution. Note that all specified tours are recomputed using the stored profile of the request. For vehicles with differing vehicle profiles create a separate ToursInExecutionRequest for each vehicle.

ToursResponse

extends ResponseBase
used by XTour
since 2.1

Contains the result of a PlanToursRequest, ChangeToursRequest or ToursInExecutionRequest. For the planTours case, all members refer to the complete plan. For the changeTours case, all members refer to the changed part of the plan. For the evaluateToursInExecution case, only the evaluated tours and their updated tour events are returned.

Field Name Type Required Default Since Description
costReport CostReport yes - 2.1 Cost related values accumulated over all tours.
tours Tour[] 0..* - 2.1 A list of tours, one for each vehicle that is used in the tour plan, referenced by the corresponding vehicle ID.
tourReports TourReport[] 0..* - 2.1 Each element contains additional information about the tour of the referenced vehicle ID.
orderIdsNotPlanned String[] 0..* - 2.1 References to orders that could not be planned in the response of a PlanToursRequest. These orders are not part of the tours.

For a ChangeToursRequest the entries depend on the use case:

  • ChangeToursAction only consisting of explicit changes:
  • ChangeToursAction with (partially) unspecified insertions:
    • Example: MoveOrdersAction with at least one unspecified insertion of type InsertionAtBestPosition
    • Unplanned orders: Each order that cannot be planned is returned as unplanned order. The target tour does not have any violations, if it was not violated before the action.
  • ChangeToursAction of type RemoveOrdersAction: All removed orders are returned as unplanned orders.

orderIdsNotPlannable String[] 0..* - 2.26 References to orders which cannot be served by any vehicle in the fleet without a violation. These orders are part of orderIdsNotPlanned. For further information about the violation types please send a FindChangeToursProposalsRequest with an InsertionPositionsForOrdersQuery as described in the integration sample Analyzing Unscheduled Orders for each order. This field is only filled in the response of a PlanToursRequest and will be empty for the response of a ChangeToursRequest.
vehicleIdsNotPlanned String[] 0..* - 2.4 References to vehicle instances that are not used in the response of a PlanToursRequest or that were planned before but are no longer planned after performing a change tours action. These vehicles are not part of the tours.
vehicleIdsWithTourViolations String[] 0..* - 2.5 References vehicle instances of tours of the response that have at least one tour violation. If the response has no tour violations, this vector is empty.
vehicleIdsWithRouteViolations String[] 0..* - 2.14 References vehicle instances of tours of the response that have at least one route violation. If the response has no route violations, this vector is empty.
vehicleIdsWithDirectDistanceEstimation String[] 0..* - 2.14 References vehicle instances of tours of the response that have at least one leg which is estimated by direct distance. If the response has no legs estimated by direct distance, this vector is empty.
violated Boolean no - 2.5 True if there is any tour violation.
routeViolated Boolean no - 2.14 True if there is at least one route violation at the leg.
storedRequestId String no - 2.5 Reference to the request that is stored in the session storage with this response as input plan. If there occur any problems with the session storage, an ObjectNotStoredLimitation is generated and this parameter is null even if storage was requested. In case of evaluateToursInExecution no storedRequestId is returned because the stored input plan does not change.

TransportOrder (abstract)

extends Order
extended by OrderWithAlternativeDeliveryDepots, OrderWithAlternativePickupDepots, PickupDeliveryOrder
since 2.1

Order to transport goods from one depot site or customer site to another.

Field Name Type Required Default Since Description
quantities TransportQuantityUnit[] (Double[]) 0..100 - 2.1 List of quantities of goods that should be transported from pickup site to delivery site. The maximum length of this list is 100. That is, up to 100 different quantity dimensions (e.g. number of pallets, weight, volume, etc.) can be distinguished. Transport orders can only be transported by a vehicle with a higher (or an equal) maximum quantity in every quantity dimension of at least one quantity scenario. The length of this list has to be the same for all transport orders and all maximum quantity scenarios of all vehicles. If and only if this list of quantities is empty for all transport orders, the list of maximum quantity scenarios of each vehicle must be empty.
serviceTimeForPickup Duration (Double) no 0.0 2.1 Overall service time at the site required to pick up the order. Additionally there may be a site dependent or vehicle dependent service time of the stop. See Service time calculation.
serviceTimeForDelivery Duration (Double) no 0.0 2.1 Overall service time at the site required to deliver the order. Additionally there may be a site dependent or vehicle dependent service time of the stop. See Service time calculation.
maximumTravelTimeBetweenPickupAndDelivery Duration (Double) no - 2.32 Restricts the maximum allowed travel time between departure from the pickup site (more precisely, the end of all service there) and arrival at the delivery site (more precisely, the beginning of any service there). When used together with multi day working hours or a daily rest rule, the field of type RestPositions must be set to ANYWHERE. Likewise, when used together with a working hours preset, the name of the preset must not end in _MULTIPLE_SINGLE_DAYS. Not supported for time-dependent driving times.

Trip

used by Tour
since 2.1

An operation schedule for a single trip. A trip contains the sequence of stops that are served. At the beginning and end of each trip the vehicle does not carry any load. A trip starts at the vehicle start location or at a depot, and ends at the vehicle end location or at a depot. See Tours and Trips.

Field Name Type Required Default Since Description
id String yes - 2.1 The reference ID of this trip. Response trips that are identical to input plan trips in stops and stop sequence have the same trip ID as the corresponding input plan trip. The ID also stays the same if the trip's position within its tour changes or if its vehicle changes. Response trips that are changed input plan trips or newly generated as result of a PlanToursRequest get a newly generated ID. Trip changes caused by a ChangeToursRequest do not change the trip ID.
stops Stop[] 1..* - 2.1 A sequence of stops along this trip. Each stop is served at a specific location, either a customer site or a depot site. The sequence of tasks within the stops is always sorted by Last In - First Out (LIFO). For more details, see Orders, Locations, and Stops.

TripReport

used by TourReport
since 2.1

More detailed information about a trip, containing an accumulated cost report.

Field Name Type Required Default Since Description
tripId String yes - 2.1 ID of the corresponding trip to this report.
costReport CostReport yes - 2.1 Cost related values for this trip.
violationReport TripViolationReport no - 2.5 Summary for tour violations of this trip.
orderGroupId String no - 2.13 If there is at least one order with a groupId in the trip, the orderGroupId of a tripReport is the groupId that occurs most often among the orders of this trip. If no order of this trip has a groupId then this field is not set. If a planToursRequest has a trip in the input plan with different groupIds among the orders, first the orderGroupId of the trip is determined and then only orders of the same groupId are inserted in this trip during automatic planning. A changeToursRequest can change the orderGroupId of a trip for example by removing orders from the trip. All changeToursActions are performed even if options of the orderGroupConsideration are not fulfilled or if the orderGroupId does not match with any of the orderGroupIds of the target vehicle. For further information please have a look at the technical concept Order Groups.

TripStartInterval

used by AddTripStartIntervalsAction, InputPlan
since 2.19

Trip start interval in which the trip must start.

Field Name Type Required Default Since Description
tripId String yes - 2.19 ID of the trip.
interval StartEndInterval yes - 2.19 Interval in which the trip with tripId must start. Start and end of the interval may be the same. The trip start interrupts a TourEvent of type BREAK or DAILY_REST.

TripViolationReport

extends ViolationReport
used by TripReport
since 2.5

Violation related information describing trips. The trip violation report contains violation summaries of its parent object, which is a trip report.

Field Name Type Required Default Since Description
tripStartIntervalExceedance Duration (Double) no - 2.19 The duration by which the end of the trip start interval is exceeded. Corresponds to tour events with violation type TRIP_START_INTERVAL.
operatingIntervalExceedance Duration (Double) no - 2.20 The duration by which the end of the driver operating interval, in which the trip start lies, is exceeded. If the whole trip lies outside of the driver operating intervals, the exceedance is calculated by the difference to the end of the last driver operating interval. Corresponds to tour events with violation type OPERATING_INTERVAL.

TweaksToObjective

used by PlanToursOptions
since 2.23

Describes special tweaks to the objective of the algorithm.

Field Name Type Required Default Since Description
avoidIntersections Boolean no false 2.23 If this parameter is set to true, the focus is to avoid intersections of edges, where an edge is a straight line drawn between two consecutive stops in a trip. The number of tours may be higher compared to the result when this parameter is set to false. If the calculation mode is set to avoid intersections, this must be set, otherwise an exception is thrown.
minimizeNumberOfTours Boolean no true 2.23 If this parameter is set to true, the algorithm plans as many orders as possible using as few vehicles as possible, even though the costs, for example driving time or distance, of the whole plan might increase. If this parameter is set to false, the algorithm plans as many orders as possible so that the total cost is minimized. Therefore it is likely that the number of tours will be higher compared to the result when this parameter is set to false.

Vehicle

used by Fleet
since 2.1

A vehicle that is used to transport goods or perform visits. In transport use cases, vehicles are mostly trucks, for customer visits, also cars may be used. Several IDs can be specified to simplify the use of multiple vehicles that are of the same type.

Field Name Type Required Default Since Description
ids String[] 1..* - 2.1 A list of unique IDs for the vehicle(s) of this type. The IDs can be used to reference a specific vehicle, for example in a response tour. For multiple identical PlanToursRequests the PlanToursResponse will always be the same. But please be aware that different IDs can lead to different results.
maximumQuantityScenarios MaximumQuantityScenario[] 0..500 - 2.1 An ordered list of scenarios for the maximum quantities of goods of different kind that this vehicle can transport. For example at most 5 pallets and 10 boxes, or 3 pallets and 20 boxes could be transported by a vehicle. Since the quantity may not be exceeded in any dimension, an order with 4 pallets and 11 boxes would not fit on the vehicle of the example. However, an order with 4 pallets and 10 boxes would fit. The length of this list has to be the same for all vehicles and for all maximum quantity scenarios of all transport orders. If and only if the list of quantities is empty for all transport orders, the list of maximum quantity scenarios of each vehicle must be empty. The order of the scenarios matters: if multiple quantity scenarios would lead to the same number of quantity scenario changes, the quantity scenarios farther in front of the vector are chosen.
quantityScenarioChangePosition QuantityScenarioChangePosition no QuantityScenarioC ... 2.26 Position in the tour where the currently chosen quantity scenario of a vehicle may be changed.
compartmentAccessRestriction CompartmentAccessRestriction no - 2.29 The compartment access restriction needs to be specified if a compartment of the vehicle can only be accessed through another compartment and it may happen that this access is blocked by loaded goods. If this restriction is specified, the compartment quantity indices must also be set. See the technical concept page for details on the compartment access restriction.
distanceMatrixId String no - 2.8 Distance matrix of this vehicle if distance mode ExistingDistanceMatrixPerVehicle is specified. Empty otherwise. If not, an exception is thrown. The distance matrix is specified by its ID, which can be retrieved in the distance matrix summary of the corresponding DistanceMatrixResponse. The ID is considered case sensitively. The distance matrix has to contain every location that is necessary for the tour planning, otherwise an exception is thrown.
startLocationId String no - 2.1 ID of the vehicle's start location. May be a vehicle location or a site. Opening intervals and service times are not considered for a vehicle's start location. If no start location is specified, it is assumed that the vehicle is available at the first stop.
endLocationId String no - 2.1 ID of the vehicle's end location. May be a vehicle location or a site. Opening intervals and service times are not considered for a vehicle's end location. If no end location is specified, it is assumed that the vehicle remains at the last stop.
drivingTimeFactor DrivingTimeFactor (Double) no 1.0 2.32 A factor to take differences between vehicles into account when no distance matrix is given or the associated distance matrix does not fit perfectly. Depending on the distance mode, the factor is multiplied with the estimated driving times or the driving times from the associated distance matrix, respectively. A factor less than 1.0 means that the vehicle is faster, a factor greater than 1.0 means that it is slower than originally estimated or calculated. A factor other than 1.0 is not supported in connection with a multiple travel times distance matrix.
serviceTimeFactorForOrders ServiceTimeFactor (Double) no 1.0 2.1 A factor that is multiplied with the service times of all orders' tasks carried out by this vehicle, for example if loading/unloading is more or less complicated than for other vehicles. A factor less than 1.0 means that the vehicle speeds up the service, a factor greater than 1.0 means that it slows the service down. See Service time calculation.
serviceTimePerStop Duration (Double) no 0.0 2.1 Vehicle dependent service time, for example for maneuvering. This service time will be considered for each stop served by this vehicle. Additionally there may be a site dependent or order dependent service time of the stop. See Service time calculation.
equipment String[] 0..* - 2.3 List of vehicle equipment. An order can only be served by the vehicle if this list is a superset of (or equal to) the order's required vehicle equipment.
orderGroupIds String[] 0..* - 2.13 List of order group IDs. If a field of the order group consideration is set to true, an order should only be served by the vehicle if a) this vector is empty, or b) this vector contains the group ID of the order. The preferences that apply to orders with the same group ID are specified in the order group consideration. See technical concept Order Groups for further details.
tourStartInterval StartEndInterval no - 2.19 Interval in which the vehicle has to start its tour. Start and end of the interval may be the same. Leaving this parameter empty means that the tour start is unrestricted. The tour start interrupts a TourEvent of type BREAK or DAILY_REST.
maximumNumberOfCustomerStops NonNegativeInteger (Integer) no - 2.23 Restricts the maximum allowed total number of customer stops, i.e. stops at customer sites, within the tour of this vehicle. If this parameter is set, maximum number of customer stops at tour restrictions must not be set, otherwise an exception is thrown. If not given the maximum number of customer stops is unlimited.
maximumDistance Distance (Double) no - 2.24 Restricts the maximum allowed total distance within the tour of this vehicle. If this parameter is set, maximum distance per tour at tour restrictions must not be set, otherwise an exception is thrown. If not given the maximum distance is unlimited. This restriction is ignored for ToursInExecutionRequests.
maximumTravelTime Duration (Double) no - 2.24 Restricts the maximum allowed total travel time within the tour of this vehicle. The travel time contains all waiting, service and driving times. Drivers' working hours may be more restrictive and enforce a lower limit. If this parameter is set, maximum travel time per tour at tour restrictions must not be set, otherwise an exception is thrown. If not given the maximum travel time is unlimited. This restriction is ignored for ToursInExecutionRequests.
maximumDrivingTime Duration (Double) no - 2.24 Restricts the maximum allowed total driving time within the tour of this vehicle. Drivers' working hours may be more restrictive and enforce a lower limit. If this parameter is set, maximum driving time per tour at tour restrictions must not be set, otherwise an exception is thrown. If not given the maximum driving time is unlimited. Not supported for time-dependent driving times. This restriction is ignored for ToursInExecutionRequests.
ignoreMixedLoadingProhibitions Boolean no false 2.25 Indicates whether the mixed loading prohibitions are relevant for this vehicle. If set to false, the mixed loading prohibitions -- if there are any -- must be respected on every trip of the vehicle. If set to true, the mixed loading prohibitions are ignored by the vehicle.
monetaryCostOptions MonetaryCostOptions no - 2.28 Monetary costs are calculated for this vehicle if scheduled. Cost totals are output in the cost reports of the response. This field only has no impact on the planning result. It does not affect the entries in the linked distance matrix or the calculation of the direct distances.

VehicleLocation

extends Location
since 2.1

A location representing a vehicle location. This location may be the start or end location of a vehicle in a tour.

No fields defined.

Position of the driver and his vehicle in a tour in execution.

No fields defined.

VehiclesForTripsQuery

extends ChangeToursProposalsQuery
since 2.14

A query to propose other vehicles for a trip, that means moving a trip to a specified position in an existing tour or to an empty vehicle. Only structurally valid positions are proposed, for details please have a look at tour structures. If violated insertion positions shall be part of the proposals, set returnViolatedTours to true. The source tour of the trip to be moved (if not empty after the move) plus the resulting tour are contained in the TourReports.

Field Name Type Required Default Since Description
tripIds String[] 1..1 - 2.14 ID of the trips to be moved. At the moment, only one trip is supported.
targetVehicleIds String[] 0..* - 2.14 Option to restrict target vehicles. If empty, all vehicles of the plan are considered as target vehicles except the current vehicle of the trip. If the current vehicle ID of the trip is part of the targetVehicleIds, it will be ignored.

ViolationReport

extended by TourViolationReport, TripViolationReport
since 2.5

Violation related information describing tours or trips. The violation report contains violation summaries of its parent object, which is either a tour report or a trip report.

Field Name Type Required Default Since Description
maximumOpeningIntervalExceedance Duration (Double) no - 2.5 The longest opening interval exceedance. Corresponds to tour events with violation type OPENING_INTERVAL.
maximumQuantityScenarioExceedance TransportQuantityUnit[] (Double[]) 0..100 - 2.5 The highest maximum quantity scenario exceedance. This always refers to the first maximum quantity scenario of the vehicle. Corresponds to tour events with violation type MAXIMUM_QUANTITY_SCENARIO.
vehicleEquipmentViolations String[] 0..* - 2.5 Contains all required vehicle equipment violations. Corresponds to tour events with violation type VEHICLE_EQUIPMENT.
restPositionViolated Boolean no - 2.5 Indicates if any daily rest is scheduled at an unexpected position according to possible rest positions that can for example be defined by multi day drivers' working hours.
customerStopPositionInTripViolated Boolean no - 2.23 Indicates if any service is scheduled at an unexpected position according to the position in trip. Corresponds to tour events with violation type CUSTOMER_STOP_POSITION_IN_TRIP.
tripSectionViolated Boolean no - 2.23 Indicates if any service is scheduled at an unexpected position according to the trip section number. Corresponds to tour events with violation type TRIP_SECTION.
mixedLoadingProhibitionsViolations MixedLoadingProhibition[] 0..* - 2.25 Contains all mixed loading prohibitions violations. Corresponds to tour events with violation type MIXED_LOADING_PROHIBITION.
routeViolated Boolean no - 2.25 Indicates if at least one of the routes between two locations is violated. This violation does not occur if ignore route violations is set to true. Corresponds to tour events with violation type ROUTE.
reachabilityViolated Boolean no - 2.25 Indicates if at least one of the routes between two locations was calculated by direct distance instead of the road network. This violation does not occur if ignore reachability violations is set to false and if distance mode is not set to direct distance. Corresponds to tour events with violation type REACHABILITY.
compartmentAccessViolated Boolean no - 2.29 Indicates if at least at one stop a compartment cannot be accessed through another compartment as the latter is too crammed according to the compartment access restriction. Corresponds to tour events with violation type COMPARTMENT_ACCESS.
maximumTravelTimeBetweenPickupAndDeliveryExceedance Duration (Double) no - 2.32 The longest occurring exceedance of the maximum travel time between pickup and delivery. Corresponds to tour events with violation type MAXIMUM_TRAVEL_TIME_BETWEEN_PICKUP_AND_DELIVERY.

VisitOrder

extends Order
since 2.1

Order to visit a customer without transporting any goods.

Field Name Type Required Default Since Description
locationId String yes - 2.1 ID of the location of the customer to be visited. This location has to be a customer site.
serviceTime Duration (Double) no 0.0 2.1 Overall service time at the site required for the visit. Additionally there may be a site dependent or vehicle dependent service time of the stop. See Service time calculation.
Enumeration

CalculationMode

used by PlanToursOptions
since 2.1

Enumeration to define the calculation behaviour of the algorithm, i.e. if the focus of calculation is on performance, quality or both.

Enumeration Value Since Description
PERFORMANCE 2.1 The algorithm's focus is on performance. A smaller search space for solutions is considered during the computation.
STANDARD 2.1 The algorithm chooses a standard trade-off between quality and performance of the algorithm.
QUALITY 2.1 The algorithm's focus is on high solution quality. A larger search space for solutions is considered during the computation.
AVOID_INTERSECTIONS 2.16 The algorithm's focus is to avoid intersections of legs. Note that the number of planned vehicles may be higher compared to the results of the calculation modes performance, standard and quality, especially for requests with many restrictions such as disjoint opening intervals. A larger search space for solutions is considered during the computation. This mode is deprecated as this feature should be enabled via a field of the same name in the tweaks to objective in the plan tours options instead.
CUSTOM 2.16 The algorithm's focus is adapted to the customer's needs. It is necessary to define the custom calculation mode configuration accordingly.
EVALUATE 2.5 The algorithm does not plan anything. A response is generated for all input tours of the request's input plan without changing these tours.
Enumeration

CompartmentSetup

used by MaximumQuantityScenario
since 2.29

The compartment setup tells whether compartment A can only be accessed through compartment B or the other way around. Compartments A and B are defined by the compartment quantity indices. See the technical concept page for details on the compartment access restriction.

Enumeration Value Since Description
ACCESS_A_THROUGH_B 2.29 Compartment A can only be accessed through compartment B. The corresponding load threshold of the compartment access restriction applies.
ACCESS_B_THROUGH_A 2.29 Compartment B can only be accessed through compartment A. The corresponding load threshold of the compartment access restriction applies.
Enumeration

FixationType

used by Fixation
since 2.1

Different kinds of fixations.

Enumeration Value Since Description
VEHICLE_ORDERS 2.1 All orders that are served by a vehicle must remain served by this vehicle. Additional orders can be assigned to this vehicle. In this case, the ID of the fixation corresponds to the vehicleId.
TRIP_TO_VEHICLE 2.7 The trip is part of the input plan and must remain "as is". It also must remain served by the same vehicle as in the input plan. In this case, the ID of the fixation corresponds to the trip ID.
Enumeration

PositionInTrip

used by CustomerSite
since 2.23

Type of a specified position of a stop at a customer site within its trip.

Enumeration Value Since Description
FIRST_CUSTOMER_STOP 2.23 A stop at a customer site with this position type has to be the very first customer stop in its trip.
LAST_CUSTOMER_STOP 2.23 A stop at a customer site with this position type has to be the very last customer stop in its trip.
Enumeration

QuantityScenarioChangePosition

used by Vehicle
since 2.26

Position at which a quantity scenario of a vehicle may be changed.

Enumeration Value Since Description
AT_STOP 2.26 The scenario may be changed between unloading and loading at a stop.
BETWEEN_TRIPS 2.26 The scenario may only be changed between a trip end and a trip start.

A type of task that can be carried out at a stop.

Enumeration Value Since Description
PICKUP 2.1 An order is picked up.
DELIVERY 2.1 An order is delivered.
VISIT 2.1 A customer is visited.

Diagrams

Operations Overview

Job Progress

Plan Tours Request

Change Tours Move Actions

Change Tours Other Actions

Change Tours Proposals

Tours Response

Order

Fleet

Location

Input Plan

Plan Tours Option

Distance Mode

Result Limitations

Tours In Execution