Options

The options object belongs in the main request body and allows you to tweak how the Routing Engine runs.

"options": {
   "traffic": "slow",
   "min_visits_per_vehicle": 5,
   "balance": true,
   "min_vehicles": true,
   "shortest_distance": true,
   "squash_durations": 1,
   "max_vehicle_overtime": 30,
   "max_visit_lateness": 15,
   "polylines": true
}

traffic: It's usually a good idea to simulate slower traffic to ensure you will never be late for a delivery. Estimated driving times tend to be more optimistic than in reality, and using this parameter will slow down driving speed. The default value is faster. Each step slows down the speed by 25%, so fast would be 25% slower from default, while very slow would be twice as slow.

min_visits_per_vehicle: Routific will optimize your routes by finding the minimum total travel time. This may lead to some vehicles being assigned only a few visits or not being assigned at all. This may not always be desired because some businesses prefer to spread out visits/orders across all drivers. This parameter allows you to specify a minimum number of visits for each vehicle. Note that we expect an integer value greater than 0.

balance: If assigning equal number of orders across your vehicles is not enough and you want them to also have balanced driving shifts across your fleet, you can use this parameter. It should only be used in conjunction with min_visits_per_vehicle. This parameter will instruct the algorithm to keep the variance across driver shift times as small as possible.

visit_balance_coefficient: Use this parameter (a number between 0.0 and 1.0) to adjust relative balance levels so that you have control over how balance is traded off with routing efficiency. 0.0 gives you a route solution that minimizes overall driving time while 1.0 gives you a completely balanced route at the expense of routing efficiency. This parameter cannot be used together with the balance and min_visits_per_vehicle parameters and will throw a 400: ERR_BALANCE_AND_MIN_VISITS_PER_VEHICLE_INCOMPATIBLE error if this happens. Only available in v1.10 and up of /vrp-long i.e. you will need to make an API call to api.routific.com/v1.10/vrp-long to use it. Note: When this option is explicitly assigned a value of 0 in the API request, it gets treated as null and is not acknowledged in the options object of the API response.

min_vehicles: Use this parameter if you are interested to minimize the number of vehicles you'd like to use to get all the jobs done. This allows you to figure out how many drivers you should call in. When using this parameter, make sure you provide ample vehicles in the input, so all the orders can be served. The idle vehicles will be empty in the solution.

shortest_distance: By default we optimize by minimizing the total driving time and working hours. In some cases – due to time-windows – your drivers might have idle-time as it waits for the next time-window. By default we take this into account, which potentially could result in more miles driven, as we'd send the drive to another location first and coming back later. If you'd rather optimize purely on shortest distance, set this parameter to true.

squash_durations: Useful when you have many stops at the same location, which could be an apartment complex. Normally, each stop has a duration value of let's say 10 minutes, which accounts for parking and finding the entrance. If you had 6 stops assigned to a driver at the same time, it doesn't take an hour in total! Use this parameter to squash the durations of each subsequent delivery at the same address. If you set it to 1, it will squash it to 1 minute, so the total duration for the above 6 stops would be 15 minutes.

polylines: When setting this option to true Routific will respond with an encoded polyline representing each vehicle's route. In addition, this will also return the distances between each stop (in meters) as well as the total distance travelled per vehicle (in kilometers). For more information on decoding the polylines refer to this help article.

avoid_tolls: This option is useful if you would like to avoid toll roads in your routes. By enabling this option, the route optimization will calculate distance and time without the use of toll roads. If polylines option is also enabled, it will return routes without the toll roads. For more information, refer to this help article.

geocoder: By-default we geocode the address strings provided in the API request using Google. But in certain cases, we've discovered that Google doesn't accurately geocode to the correct street while routing. A popular example of this being a driver getting routed to a back alley of the building, rather than the main street where the building can be accessed from. If you are experiencing similar issues with your routes, you can set to geocode with Here services, which will get your drivers routed to the right street to access the building.

Unless explicitly stated, all the options parameters listed here are supported on both the /vrp-long and /pdp-long endpoints.

📘

Allow lateness and overtime

Sometimes you want to be a little flexible with your time-window constraints. Normally, when you set time-window constraints, the Routific algorithm will consider them as hard requirements. Even if Routific thinks you'll be 1 minute late, it will return it in the unserved object.

If you need to schedule all your stops, and cannot afford any unserved – even if it means being late or working your drivers overtime – then you can use these two options parameters:

max_vehicle_overtime: This sets the maximum number of minutes a driver is allowed to work overtime. Note that if all stops can be served within a normal shift, that will always be preferred.

max_visit_lateness: This sets the maximum number of minutes you can be late for any of your stops. We only schedule something late if it is going to be unserved otherwise. Also note that the algorithm will minimize and spread out lateness as much as possible; the algorithm favors 5 orders being late by 2 minutes over 1 order being late by 10 minutes.

Both max_vehicle_overtime and max_visit_lateness can be set to a maximum value of 71582788 (maximum u32 integer size in seconds, in case you're curious).

When you use these options, the output in the response will include new fields:

{
  ...,
  "total_visit_lateness": <minutes>,
  "num_late_visits": <number>,
  "total_overtime": <minutes>,
  "vehicle_overtime": {
    "vehicle1": <minutes>,
    "vehicle2": <minutes>
  },
  "solution": {
    "vehicle1": [
      ...
      {
        "location_id": "visit1",
        "too_late": true,
        "late_by": <minutes>
      },
      ...,
      }
    ]
  }
}

There are 4 new fields in the response:

• total_visit_lateness indicates the actual total number of minutes the solution is violating the time-windows
• num_late_visits is the count of visits that have been scheduled late
• total_overtime is the total number of minutes your drivers are working overtime
• vehicle_overtime is an object that shows a break-down of the number of minutes each driver is working overtime
• In the actual solution object, on the stops that are late, we'll return the number of minutes it was late_by.