Events Reference

What is an Event?

An event represents what in the market is called delivery, pickup, shipment or order.

Adding event with suggestion

Adding an event with the suggestion(s) is a synchronous request that adds the event in the cheapest spot possible and returns suggestions for the event as per the suggest request. Find the example here.

Event Entity Reference

Name	Format	Description	Required	Example
id	GUID	Unique event 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
address	Address	The real address where the event is happening. Either address or geo_point has to be provided. Both of them can not be removed from the request fields.	False	See Address
geo_point	Geolocation	The geolocation where the event is happening	False	{"latitude": 52.12296,"longitude": 5.05141}
created	Date-time	The Date-time in which the Event was created	N/A	2017-11-13T14:30:00Z
modified	Date-time	The Date-time in which the Event was modified last time	N/A	2017-11-13T14:30:00Z
external_data	Object	The external data introduced when the Event was created	False	{"customer_name": "Plotwise"}
min_time	Date-time	The minimum time in which the event should happen. If not provided: first (non-depot) delivery timeslot from the bucket will be used.	False	2019-06-04T04:00:00Z
max_time	Date-time	The maximum time in which the event should happen. If not provided: last (non-depot) delivery timeslot from the bucket will be used.	False	2019-06-04T04:00:00Z
current_state	String	The name of the current Event state	N/A	preparing
old_state	String	The name of the previous Event 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	initialized/event/391a3fe7-6dc8-4c4f-9d2a-1cb84ac55e31/nofits
sort_key	Integer	The position in the route this event is occupying. Notice that the sequence of numbers does not need to be contiguous.	N/A	2
bucket	GUID	The Bucket Guid where the Event belongs to	N/A	2227b2f0-5e73-447c-9022-07ec409921c6
route	GUID	The Route Guid where the Event belongs to	N/A	2227b2f0-5e73-447c-9022-07ec409921c6
event_type	Enum	New in v2 The type of event: delivery, depot, or break	N/A	delivery
capacity_vector	Capacity	The amount of capacity that the event occupies in the resource from the depot until the event is visited. Mutually exclusive with the capacity field in the algorithm fields. Setting Null to a capacity of an event means it is 0.0. Either capacity_vector or capacity (inside of the algorithm_fields) has to be provided. Both of them are considered optional.	False	{"capacity_1":12.3, "capacity_2": null, "capacity_3": 0.0, "capacity_4": null, "capacity_5": null }
pickup_capacity_vectory	Capacity	The amount of capacity occupied after visiting the event until the next depot stop (either an intermediate depot or the last depot).	False	{"capacity_1":12.3, "capacity_2": null, "capacity_3": 0.0, "capacity_4": null, "capacity_5": null }
resource_event_tags	Array of Strings	The tags used to pair up resources with this event. The Resource.resource_event_tags must contains all of the tags present on the event to be seen as a valid potential match. You can specify up to five tags.	False	["tag1", "tag2"]
route_event_tags	Array of Strings	The tags used to pair up routs with this event. The Route.route_event_tags must contains all of the tags present on the event to be seen as a valid potential match. You can specify up to five tags.	False	["tag1", "tag2"]
timeslot_windows	Array of Timeslot	The set of timeslots that will be used for suggestions	False	[{"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"}]

Algorithm fields

Name	Format	Description	Required	Example
stop_time	Float	Duration in seconds the Event should take as a maximum	True	752.2
eta	Date-time	The estimated date-time in which the Event should happen	N/A	2019-06-04T04:00:00Z
capacity	Float	The volume/size/etc the package is. No unit is used for this field, is up to the client to be consistent on it.	False	19.0
time_to_next	Float	Time in seconds the between this event and the next one	N/A	3214.3
dist_to_next	Float	Distance in meters the between this event and the next one	N/A	3214.3
selected_timeslot	Timeslot	The selected timeslot based on the picked suggestion for this event	N/A	{"min_time": "2019-06-04T04:00:00Z", "max_time": "2019-06-04T05:30:00Z"}

Address

Name	Format	Description	Required	Example
street	String	The street name	False	Donker Curtiusstraat
postalcode	String	The postal code	False	1051JN
house_number	Integer	The house number	False	8
house_number_addition	String	The house addition	False	I
city	String	The city name	False	Rotterdam
country	String	The country name	False	Netherlands
region	String	The region name	False	Europe

States

New

The State in which the event is created. Nothing happened with it at this point.

Initializing

The event is being initialized and soon will be added to a route.

Preparing

This is an internal state in which the event goes through when it's created at the same time that suggestions are.

Initialized

The event is initialized so it is now going to be temporarily placed in a route. This is a brief state.

Prepared

This is an internal state in which the event goes through when it's created at the same time that suggestions are.

Cancelling

The event is being cancelled and will either transition to state cancelled or errored.

Cancelled

At this state the event is not going to be used for anything but statistics and record of activity.

Planned

The event is assigned to a route. At this point, it is possible to request for time-slot suggestions for this event. If a time-slot suggestion is already approved only that one will be returned, and this event becomes a restriction on the other events when are introduced to the bucket. If multiple time-slot suggestions are returned, means this event has a "flexible" time, so it can still be changed to another route/time.

Errored

At any time, if there is an error with this event, this event will become errored and it needs to be re-created. See more about potential errors here.

Gotchas

• Make sure that all expected event min_time and max_times are scheduled outside first and last timeslots of timeslot_windows of the bucket.
• The min_time and max_time make a window inside which the delivery needs to be made. To be safe, set that range of cover the time between the first and last timeslots of timeslot_windows of the bucket.
• Make sure that the definition of capacity is the same for resources and events.
• Make sure that stop_time is non-negative value.
• There is no unique check for id fields in timeslot_windows. If you provide the same id for different windows, the first match id will be used.

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
3	Event	min time	>=	at least one event/bucket suggestion timeslot min time (same timeslot as rule #4)
4	Event	max time	<=	at least one event/bucket suggestion timeslot max time (same timeslot as rule #3)

Examples

Find the examples here