VRP request

This VRP request schema is used for solving a Vehicle Routing Problem. It consists of resources, jobs, options
and weights.

NameTypeRequiredDescription
resources[Resource]trueList of Resources
jobs[Job]trueList of Jobs
optionsOptionsfalseOptions for solver configuration
weightsWeightsfalseWeighting the constraints
hookstring(uri)falseWebhook for getting notified after request is solved.

Job

A job to be performed by a resource.

NameTypeRequiredDescription
namestringtrueUnique description
durationintegerfalseService duration of the job
locationLocationfalseJob location
priorityintegerfalsePriority of the job will ensure that it is included in the planning over other lower priority jobs.
tags[Tag]falseA tag is a string that can be used to link jobs to resources.
windows[TimeWindow]falseList of start/end date/time combinations.
durationSquashintegerfalseWhen a job is performed at the same location as another job, durationSquash ensures that the 2nd job' service time is reduced to this value. Example: duration=600 and durationSquash=30 means that the 2nd job will only take 30 seconds to perform.
plannedDatedatefalseFixed date on which this job is already planned and should hence be taken into account in the planning.
plannedResourcestringfalseName of the resource to which this job is already planned and should hence be taken into account in the next planning.
plannedArrivaldate-timefalsePlanned arrival time The second of day at which the job is planned to complete. The difference with the actual arrival time is scaled in the score with plannedWeight.
hardbooleanfalseIn the case of partial planning, this indicates whether this job should be integrated into the planning or not.
hardWeightintegerfalseIn the case of partial planning, this indicates the weight of this job.
paddingintegerfalsePadding time (in seconds) before and after the job.
allowedResources[string]falseResources that are allowed to be assigned to this job.

TimeWindow

A time window is a time period in which a job can be performed.

NameTypeRequiredDescription
fromdate-timetrueDate time start of window
todate-timetrueDate time end of window
weightintegerfalseWeight constraint modifier
hardbooleanfalseHard constraint violation of DateWindow

Tag

NameTypeRequiredDescription
namestringtrueTag restriction name which can force some Jobs to be scheduled by Resources with the same tag
hardbooleanfalseHard or soft constraint.
weightintegerfalseValue of the weight. This will be on the same level as travel time in the case of soft constraint.

Location

NameTypeRequiredDescription
latitudenumbertrueLatitude (WGS84)
longitudenumbertrueLongitude (WGS84)

Resource

A resource is a vehicle or person that can perform jobs.

NameTypeRequiredRestrictionsDescription
namestringtruenoneUnique name
startLocationfalsenoneStart location
endLocationfalsenoneEnd location
shifts[Shift]truenoneShift definition of a Resource over course of planning period
maxDriveTimeInSecondsintegerfalsenoneMaximum drive time in seconds
tags[string]falsenoneTag requirements
maxDriveTimeintegerfalsenonenone
maxDriveTimeJobintegerfalsenonenone
categoryCategoryfalsenonenone
regionLocationfalsenoneGeographical Location in WGS-84
rules[Rule]falsenonenone
{
  "name": "R-1",
  "start": {
    "latitude": 50.0987624,
    "longitude": 4.23849204
  },
  "end": {
    "latitude": 50.0987624,
    "longitude": 4.23849204
  },
  "shifts": [
    {
      "from": "2022-03-10T12:15:50",
      "to": "2022-03-10T12:15:50",
      "start": {
        "latitude": 50.0987624,
        "longitude": 4.23849204
      },
      "ignoreTravelTimeToFirstJob": true,
      "ignoreTravelTimeFromLastJob": true,
      "breaks": [
        {
          "duration": 1800,
          "start": "2022-03-10T12:15:50",
          "end": "2022-03-10T12:15:50"
        }
      ]
    }
  ],
  "tags": [
    "Technician"
  ],
  "rules": [
    {
      "period": {
        "start": "2007-12-01",
        "end": "2007-12-31"
      },
      "minWorkTime": 0,
      "maxWorkTime": 0,
      "minServiceTime": 0,
      "maxServiceTime": 0,
      "minDriveTime": 0,
      "maxDriveTime": 0
    }
  ]
}

Shift

NameTypeRequiredDescription
fromdate-timetrueStart of the shift datetime
todate-timetrueEnd of the shift datetime
startLocationfalseStart location
endLocationfalseEnd of the shift datetime
ignoreTravelTimeToFirstJobbooleanfalseIgnore the travel time from the start location to the first job
ignoreTravelTimeFromLastJobbooleanfalseIgnore the travel time from the last job to the optional end location
overtimeEnddate-timefalseMaximum overtime time.
breaks[WindowBreak]falseMaximum overtime time.

Rule

{
  "period": {
    "start": "2007-12-01",
    "end": "2007-12-31"
  },
  "minWorkTime": 0,
  "maxWorkTime": 0,
  "minServiceTime": 0,
  "maxServiceTime": 0,
  "minDriveTime": 0,
  "maxDriveTime": 0
}

NameTypeDescription
periodPeriodSubset of the planning period
minWorkTimeintegerMinimum total work time in seconds
maxWorkTimeintegerMaximum total work time in seconds
minServiceTimeintegerMinimum service time in seconds
maxServiceTimeintegerMaximum service time in seconds
minDriveTimeintegerMinimum drive time in seconds
maxDriveTimeintegerMaximum drive work time in seconds

Period

NameTypeRequiredDescription
fromdate-timetruenone
todate-timetruenone

Example:

{
  "from": "2007-12-01",
  "to": "2007-12-31"
}

WindowBreak

NameTypeRequiredDescription
durationintegertrueBreak duration in seconds
fromdate-timetrueEarliest start for a break
todate-timetrueLatest start for a break
{
  "duration": 1800,
  "from": "2022-03-10T12:00:00",
  "to": "2022-03-10T12:45:00"
}

This means a 30 minute break somewhere between 12:00 and 12:45 on 10 March 2022.

Weights

Weights are modifiers for the objective function. They are used to influence the score calculation on the soft level.
Everything is compared with Travel Time (in seconds).

NameTypeDescription
priorityWeightintegerWeight modifier for job.priority that ensures that priority jobs are scheduled. Note that this does not make sure that they are scheduled sooner.
workloadSpreadWeightintegerWeight modifier for service time per vehicle day.
travelTimeWeightintegerWeight modifier for travel time.
plannedWeightintegerWeight modifier for planned vehicle and planned date requirement.
asapWeightintegerWeight modifier scheduling jobs as soon (on day basis) as possible.
minimizeResourcesWeightintegerWeight modifier when selecting a resource to have at least 1 job assigned. When minimizeResourcesWeight is set to 1800 then it means that only having a detour of half an hour would start to trigger having an extra resource.
{
  "priorityWeight": 1,
  "workloadSpreadWeight": 1,
  "travelTimeWeight": 1,
  "plannedWeight": 1,
  "asapWeight": 1,
  "minimizeResourcesWeight": 1
}

Options

NameTypeDescription
partialPlanningboolean¦nullIf you do not need to assign every job to a vehicle, then set partialPlanning: true.
minimizeResourcesboolean¦nullMinimise the vehicle useage or minimise total travel time. Two different objective functions. Can be extra enforced with minimizeResourcesWeight.
trafficnumber(double)¦nullModifier to travel time for traffic. If you want actual traffic information, use HERE or TomTom map integration.
polylinesboolean¦nullLet our map server calculate the actual polylines for connecting the visits. Processing will take longer.
fairWorkloadPerTripboolean¦nullIf true, the workload (service time) will be spread over all vehicles and all days. (interacts with Weights.workloadSpreadWeight and options.workloadSensitivity)
fairWorkloadPerResourceboolean¦nullIf true, the workload (service time) will be spread over all days of one vehicle. (interacts with Weights.workloadSpreadWeight and options.workloadSensitivity)
snapUnitinteger(int32)¦nullThe smallest steps in arrival time to which results will be snapped. The snapping policy is round-up and is used at runtime, implying it influences the score calculation. Unless a post-calculation feature such as job padding is used, any calculated arrival time in [391, 395] with a snapUnit of 5 will yield 395. Fallback value for Options.use_snapUnit_for_waitRange.
workloadSensitivitynumber¦nullSensitivity factor on fairness

What’s Next