Routes Reference

What is a Route?

A route contains information about when and where a resource can operate.

This 1 Route object can belong to one and only 1 Bucket. This 1 Route object can belong to one and only 1 Resource. This association will be done by the planning service.

Route Entity Reference

Name	Format	Description	Required	Example
id	GUID	Unique route reference that is generated by the system	N/A	1227b2f0-5e73-447c-9022-07ec409921c6
algorithm_fields	Algorithm fields	A set of attributes used by the algorithm to generate the plan	True	See Algorithm fields
events	Array of Events	List of events in this route	N/A	See Events
created	Date-time	The Date-time in which the Route was created	N/A	2017-11-13T14:30:00Z
modified	Date-time	The Date-time in which the Route was modified last time	N/A	2017-11-13T14:30:00Z
external_data	Object	The external data introduced when the Route was created	False	{"customer_name": "Plotwise"}
current_state	String	The name of the current Route state	N/A	planned
old_state	String	The name of the previous Route state	N/A	new
state_reason	String	The cause of the current state, useful to troubleshoot when the entity reaches an error state	N/A	initializing/route/391a3fe7-6dc8-4c4f-9d2a-1cb84ac55e31/errors
bucket	GUID	The Bucket Guid where the Route belongs to	N/A	2227b2f0-5e73-447c-9022-07ec409921c6
resource	GUID	The Resource Guid assigned to this Route	N/A	2227b2f0-5e73-447c-9022-07ec409921c6
capacity_threshold	Float	New in v2 A value that needs to be filled with a value != 1.0 for a route to be considered for splitting. This must be set to enable Intermediate Depots. If this is not set, the default value will be used and Intermediate Depots will not be enabled. Either capacity_threshold or capacity_threshold_vector has to be provided.	False	0.8
time_threshold	Float	New in v2 A value that needs to be filled with a value != 0.0 for a route to be considered for splitting. This must be set to enable Intermediate Depots. If this is not set, the default value will be used and Intermediate Depots will not be enabled. The time_threshold should be specified along with the capacity_threshold or capacity_threshold_vector.	False	0.7
minimum_trip_length	Integer	New in v2 This value is deprecated. Default: 0	False	7200
intermediate_depot_duration	Integer	New in v2 The amount of time spent at an intermediate depot in seconds. Notice that this is a constant value throughout a given shift. Default: 0	False	1800
capacity_threshold_vector	Capacity	Same as capacity_threshold but allows multiple values, mutually exclusive with capacity_threshold. null or omitting a value defaults to 1.0	False	{"capacity_1": 0.5, "capacity_2":1.0, "capacity_3": null, "capacity_4":null, "capacity_5": null}
resource_route_tag	String	Tag used to pair resources with matching routes. A tag cannot be longer than 32 characters and can only contains letters, numbers, underscores, and hyphens.	False	"early_shift"
break_geopoint	Geolocation	The geolocation in which breaks should take place when scheduled. When not filled, breaks will happen on the route at the geopoint of either the preceding or succeeding event.	False	{"latitude": 52.12296,"longitude": 5.05141}
route_event_tags	Array of Strings	The tags used to pair up events with this route. The Event.route_event_tags must be a subset of this attribute to be considered as a match. You can specify up to five tags.	False	["tag1", "tag2"]
time_cost	Float	Additional cost per second of shift resulting from planning this route will impact planning quality	False	0.0012

Algorithm fields

Name	Format	Description	Required	Example
departure_stop	Stop	The first stop in the route, usually a Depot	True	See Stop
arrival_stop	Stop	The last stop in the route, usually a Depot	True	See Stop
timeslot_windows	Array of Timeslot	The set of timeslots the drivers can pick up or deliver. The first and the last must match the departure and arrival stop times	True	[{"min_time": "2019-06-04T04:00:00Z","max_time": "2019-06-04T05:30:00Z"},{"min_time": "2019-06-04T05:30:00Z","max_time": "2019-06-04T10:00:00Z"}]
break_duration	Integer	Duration in seconds the breaks in this route should take as a maximum	False	752
break_interval	Integer	Interval in seconds in which the break is going to happen. This duration must be at least twice as long as the break duration.	False	752

States

New

At this point, this route is created and will be filled with events in any state depending on the restrictions defined by its creation attributes.

Planned

The route is planned, this is its last state.

Cancelled

State in which the route is cancelled by the client.

Errored

If any error happens during the plan generation the route moves to this state. See more about potential errors here.

Available actions

Cancel

Action in which a certain route is cancelled.

When a cancel action is given, the events on the route will be re-planned on other routes as much as possible. Events that could not be re-planned will become unplannable events - they will go into the cancelled state with a state reason that matches the cancelled route uuid.

Gotchas

• Notice that the capacity_threshold and time_threshold attributes are mandatory if you want to use the intermediate depots feature.
• The first and last timeslot in the timeslot_windows are for the delivery van loading and unloading times at the beginning and the end of the route.
• There should thus be at least 3 timeslots in the timeslot_windows list. 2 for depots and at least 1 for delivery. The departure_stop describes the earliest and latest times that the route can leave the depot, and the arrival_stop describes the earliest and latest times that it can come back.
• min_time of the departure_stop (the first timeslot_windows) should be before max_time of the arrival_stop (the last timeslot_windows).
• min_time of the arrival_stop should be the same as the max_time of the departure_stop.
• max_time of the arrival_stop should be the latest that the route can come back to the depot arrival_stop.
• ALL datetimes in the JSON should be in UTC!
• Follow the format: "2017-11-13T14:30:00Z"
• All stop_times are in seconds. It is always an integer.
• Send in at least as many routes as resources. Because a resource can be added to either the morning shift or evening shift. Thus you can send in more resources than routes but not the other way around.

Validations to keep in mind

Rule #	Where	condition left	logic	condition right
1	ALL	min time	<	max time
2	Bucket + Route + Event Suggestions	first timeslot min time	<	last timeslot max time

Examples

Find the examples here