route

A route represents an ordered collection of jobs. The route object contains details about locations, allowed start time windows, allowed dates, priorities, loads, and required or disallowed attributes. These details affect which jobs the optimizer chooses to place on the route, and when. All routes must have an id.

Name Type Description
allow_ferries boolean If enabled, the driver can utilize ferries. Defaults to the value of settings.defaults.allow_ferries if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.
allow_toll_roads boolean If enabled, the driver can make use of toll roads. Defaults to the value of settings.defaults.allow_toll_roads if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.
allow_u_turns boolean If enabled, the driver can make u-turns. This is disabled if same_side_routing is enabled. Defaults to the value of settings.defaults.allow_u_turns if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.
breaks driver_break[] The driver breaks that should be inserted onto the route. See Routing with Driver Breaks.
breaks_relative_to_start boolean Defines if the break start time is relative to the shift start. Defaults to false. See Routing with Driver Breaks.
cost_per_hour float The number of US$ per hour worked. Used for optimization. Defaults to the driver's cost_per_hour if a driver is specified for the route, otherwise defaults to the value of settings.defaults.cost_per_hour.
cost_per_km float The number of US$ per kilometer driven. Used for optimization. Defaults to $0.07677.
custom custom User-supplied custom fields that are returned unmodified in the response. These have no effect on optimization.
date date The date of the route. See Routing with Dates.
depot depot or id A convenience field that sets both start_depot and end_depot. Use this instead of location if IDs are required.
driver driver or id The driver of this route.
driving_speed_percentage float Percentage of the expected speed that the route will be driven at. This is useful for taking into account heavy traffic. Stacks with vehicle.driving_speed_percentage; for example, if a route and its vehicle both have a driving speed percentage of 50, the overall speed for the route is reduced to 25%. Defaults to the value of settings.defaults.driving_speed_percentage.
enable_end_stem_time boolean Defines if the optimization includes the effect of the time it takes to drive from the last job to the depot. Defaults to the value of settings.defaults.enable_end_stem_time.
enable_start_stem_time boolean Defines if the optimization includes the effect of the time it takes to drive to the first job. Defaults to the value of settings.defaults.enable_start_stem_time.
end_depot depot or id The end depot. Use with start_depot instead of end_location if IDs are required.
end_location marker or id The end location, or the id of a marker defined elsewhere in the request. Defaults to driver.end_location if a driver is specified for the route.
end_time timespan If using optimize_start_time, set this field to determine how late the shift can end. Defaults to the value of settings.defaults.end_time, if provided. See Routing with Shifts.
fixed_cost float The number of US$ for using this route. If the route is empty, this cost does not apply. Used for optimization.
has_next_multiday_day boolean If true, this route is part of a multi-day route that continues tomorrow. See Routing with Multi-day Routes.
hazmat_load_type hazmat_load_type A comma-separated list of the types of hazardous material carried by this vehicle. Affects access to certain roads. Only applies when vehicle_type is truck. Defaults to the value of settings.defaults.hazmat_load_type. Requires Advanced Optimizer Settings.
height_cm float The height of the vehicle, in centimeters. Affects access to certain roads. Defaults to the value of settings.defaults.height_cm if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.
id id Unique ID of the route.
jobs job[] or id[] The jobs on the route. If this is provided for a build call, there is no guarantee that these jobs will remain on this route. A route should never be provided with both jobs and stops.
kingpin_to_axle_cm float The kingpin is the point at which the trailer in a tractor-trailer pair attaches to the tractor. This length represents the longest straight line of the vehicle. It gives an indication of the manuverablity of the vehicle and affects access to certain roads. Defaults to the value of settings.defaults.kingpin_to_axle_cm if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.
length_cm float The length of the vehicle, in centimeters. Affects access to certain roads. Defaults to the value of settings.defaults.length_cm if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.
load_capacities load_amount[] The total amount of loads that can be delivered by the route per metric. Metric names must not be duplicated in this list, and only up to four metric names may be used in a request. Omitted metrics indicate no limit. Not compatible with load_capacity. See Routing with Capacities.
load_capacity float The total amount of load that can be delivered by the route. Not compatible with load_capacities. See Routing with Capacities.
location marker or id A convenience field that sets both start_location and end_location. Defaults to driver.location if a driver is specified for the route.
max_driving_time timespan The maximum time the driver can spend driving the route. This is useful for meeting Hours of Service regulations. See Routing with Shifts.
max_jobs_on_route integer The maximum number of jobs the route can contain. This is useful for simple vehicle capacity planning. See Routing with Capacities.
max_working_time timespan The maximum total time of the route. Defaults to the value of settings.defaults.max_working_time, if provided. See Routing with Shifts.
name name The name of the route.
normal_working_time timespan The total time on route before overtime rates must be paid. Defaults to the value of settings.defaults.normal_working_time, if provided. See Routing with Shifts.
number_of_axles integer The number of axles. This setting allows vehicles with more axles to carry more weight on some weight-restricted roads. Defaults to the value of settings.defaults.number_of_axles if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.
number_of_trailers integer The number of trailers. Used to avoid roads with legal restrictions on vehicles with items in tow. Defaults to the value of settings.defaults.number_of_trailers if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.
number_of_wheels integer The number of wheels. This setting allows vehicles with more wheels to carry more weight on some weight-restricted roads. Defaults to the value of settings.defaults.number_of_wheels if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.
optimize_start_time boolean Allow the route to start after start_time if it is efficient. Defaults to the value of settings.defaults.optimize_start_time. See Routing with Shifts.
optimizer_assigned_vehicle vehicle or id The vehicle assigned to this route by a build. This is useful for chaining requests using the return_request field. Can be overridden by vehicle, and ignored in build requests. See Routing with Vehicles.
overtime_cost_per_hour float The number of US$ per overtime hour worked, overtime hours occur when a route's duration exceeds normal_working_time. Used for optimization. Defaults to the driver's overtime_cost_per_hour if a driver is specified for the route. Otherwise, defaults to settings.defaults.overtime_cost_per_hour, or, if no default is provided, the value of 1.5 × cost_per_hour.
response route_response The calculated values for this route, if it has previously been returned from a request. See Full vs Partial Responses. These have no effect on optimization and are overwritten by the calculated values from the new request.
route_attributes string[] The attributes provided by this route. Use with job.required_route_attributes and job.disallowed_route_attributes. See Routing with Attributes.
same_side_routing boolean If enabled, the driver must stop on the same side of the road as the job they are delivering to. Defaults to the value of settings.defaults.same_side_routing if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.
start_depot depot or id The start depot. Use with end_depot instead of start_location if IDs are required.
start_location marker or id The start location, or the id of a marker defined elsewhere in the request. Defaults to driver.start_location if a driver is specified for the route.
start_time timespan The time of day when the driver starts at the start location. Defaults to the value of settings.defaults.start_time, if provided. See Routing with Shifts.
stops stop[] The stops on the route. If this is provided for a build call, there is no guarantee that these stops will remain on this route. A route should never be provided with both stops and jobs.
time_on_site_at_end_location timespan The amount of time spent at the end location (for example, for unloading the vehicle). Defaults to vehicle.time_on_site_at_end_location if a vehicle is specified, otherwise defaults to settings.defaults.time_on_site_at_end_location.
time_on_site_at_return_to_depot timespan The amount of time spent at a return-to-depot (for example, for loading or unloading the vehicle). Defaults to vehicle.time_on_site_at_return_to_depot if a vehicle is specified, otherwise defaults to settings.defaults.time_on_site_at_return_to_depot. See Routing with Capacities.
time_on_site_at_start_location timespan The amount of time spent at the start location (for example, for loading the vehicle). Defaults to vehicle.time_on_site_at_start_location if a vehicle is specified, otherwise defaults to settings.defaults.time_on_site_at_start_location.
unladen_weight_kg float The weight of the vehicle in kilograms when not carrying any load. Affects access to certain roads. Defaults to the value of settings.defaults.unladen_weight_kg if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.
vehicle vehicle or id The vehicle for this route. See Routing with Vehicles.
vehicle_type string The type of vehicle. Can be set to the following: car, truck, auto, straight_truck, standard_single_truck, standard_double_truck, intermediate_double_truck, long_double_truck, or standard_triple_truck. The vehicle type affects access to certain roads. Defaults to settings.defaults.vehicle_type. Requires Advanced Optimizer Settings.
weight_kg float The weight of the vehicle, in kilograms. Affects access to certain roads. Defaults to the value of settings.defaults.weight_kg if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.
width_cm float The width of the vehicle, in centimeters. Affects access to certain roads. Defaults to the value of settings.defaults.width_cm if set, otherwise defaults to a value based on the vehicle_type. Requires Advanced Optimizer Settings.

Example

{
  "id": "route0",
  "date": "",
  "start_time": "08:30",
  "max_working_time": "08:00",
  "start_location": "-43.549062, 172.642059",
  "end_location": "-43.549062, 172.642059",
  "load_capacity": 10,
  "jobs": [
    "job0",
    "job1",
    "job2"
  ]
}

The example above represents route0 that starts at 8:30 AM from latitude -43.549062, longitude 172.642059. It is expected that 8 hours is required to complete the route and return to the same location. The vehicle to be used on the route can carry 10 units of load. The following jobs will be completed during the route: job0, job1, and job2.

See Also