NAV
shell python javascript

Elastic Optimisation Service (EOS)

In Greek mythology the Goddess Eos is literally the dawn. She is the titan which brings light everyday.

EOS provides both Slot booking and dynamic scheduling capabilities to extend the Vortex algorithm product. It provides the following key benefits:

The Vortex algorithm has many features and an extremely rich and expressive API:

Licence

The use of this application is subject to the Trakm8 End User License Agreement (EULA) and by accessing the application, you agree that any use you make of the application shall be in strict compliance with the EULA. The EULA is available on request. Contact information for Trakm8 Limited is available at www.trakm8.com. Software distributed under the EULA is distributed on an "AS IS" basis WITHOUT WARRANTY OF ANY KIND, either express or implied. Copyright © 1999-2019 Trakm8 Limited. All Rights Reserved. Use of this application is also subject to certain third party terms which are available at: https://legal.here.com/terms/b2bserviceterms/en

EOS Dynamic Scheduler

EOS is a dynamic scheduler which provides automated schedule optimisation for a wide range of vehicle routing problems including deliveries, service, and collections.

This service provides incremental and background optimisation; it supports adding / deleting / updating jobs and slot booking. The optimised plan can be requested at any time to provide a very quick response.

This service is closely related to the Vortex optimisation algorithm. The service shares many data types with Vortex. Under the hood this service uses the Vortex algorithm.

The key features are:

A key feature of this service is that the schedule can be requested at any time. Optimisation continues automatically in the background until completed.

Note: Schedule plans may not necessarily be completed or optimal at the time you request the plan. The plan indicates if its finished or not. Its necessary to allow some time after adding the last job for the optimisation to complete.
The amount of time depends on the complexity of the problem which include the number of orders and the constraints.

Slot booking

Last mile delivery problems often require a near instant response for integration with a customer facing shopping basket. The shopping basket user will want to choose a home delivery time slot from a list of choices. The full list of choices need to be calculated based on availability of vehicles, drivers, spare capacity and geography. Presenting many delivery options to the customer requires an algorithm to quickly calculate all the possibilities. Full optimisation takes a long time; far too long for shopping basket integration where the response to the customer needs to be sub 500ms. To overcome this a slotting algorithm provides a very fast way to quickly establish the available time slots without the need for full optimisation.

A delivery slot is a wide time window constraint (e.g. 2-hour slot, 2pm to 4pm).

Job booking

Real-time job booking applications require jobs to be added throughout the day and schedules to be created when required without having to wait. This service supports the add hoc adding of jobs throughout the day while optimising in the background. The schedule can be requested at any time.

Multiple sessions

The API supports multiple sessions and uses a simple OPEN and CLOSE approach. Typically each depot would have its own session and a session may be kept open indefinitely as long as there is activity on the session. A single depot could have multiple sessions if there are multiple unrelated delivery problems to solve. This allows depots to be created, deleted, and even for small groups of depots to work together on a single scheduling problem - for example if you want to share vehicles between depots.

API Summary

The EOS Scheduler supports HTTPS Restful web services and uses the create, read, update, and delete (CRUD) verbs with a JSON structured payload. The API uses the Vortex algorithm objects. The notation VortexDriversObject means the Vortex JSON object for Drivers. The Vortex algorithm documentation can be used.

The general sequence for slot booking is as follows:

Sequence API Description
1 GET session Open a session for each depot. You should leave the session open indefinetely. It will return a sessionID which is required for all subsequent API calls relating to this session. The session will automatically timeout and close after idle [time]. Its acceptable to have a long idle time such as 24hrs. The purpose of the timeout is to automatically clean up old sessions. A session ideally would have a single depot, but may have multiple depots.
2 POST resources Add depot, vehicles and drivers into the session. The optimiser will use these resources for creating schedules. Don't add the same resource into multiple sessions.
3 POST slots Add slots for the next month(s) into the session. You can add slots for a specific day, or by pattern. When you add slots you specify the start and end time for the slot.
4 GET slots/available Call Get slots available given a specified date range for a job. Get slots available will calculate which slots have enough capacity and travel time for the given job. It returns a list of slots available with capacity details.
5 POST slots/book Book the selected slot with the given job.
6 Repeat sequence (4..5) to continue to do online booking.
7 Update resources Change driver, vehicle availability if necessary (e.g. driver is poorly, or vehicle service)
8 GET plan Get the plan for a specific date (e.g. tomorrow). Check to make sure the plan is finished - check for a HTTP 200 response. If you get a HTTP 202, then the algorithm is still processing and may need more time.

API Details

This section details the API parameters and discussed how to use them.

Session Parameters

This section outlines the parameters supported by EOS sessions. The EOS/Vortex system is designed for flexibility—any attributes not listed in the table below are automatically passed through to the Vortex top level. For details on supported attributes at the Vortex top level, see Vortex Version 2 Request

Key Description
Algorithm Default: "auto". This specifies the algorithm to be used to solve the problem in hand, if it is not passed (or configured as auto), EOS will decide the best algorithm to use.
ContextID Default: "". This specifies the parent context ID for this session, sessions could be configured as stand-alone or as part of a context. When ContextID is empty string or missing, session is considered as stand-alone.
ContinueWithout ImprovementTime Default: "5m". ContinueWithoutImprovementTime is a time (see Time Strings Format in Developer Guide) indicating a stopping condition, the algorithm execution will stop if there is no improvements on the current results for longer than ContinueWithoutImprovementTime.
DeleteExpiredSecond Default: 604800. Time to wait (in seconds) before an expired objects/plans are automatically deleted from active session.
FinalOutputChoice Default: "BestDistance". The final output is, by default, the complete set of solutions, which will vary in terms of the tradeoffs between cost, mileage, overtime, and so on. With this key, however, you can apply one of the three values: "BestCost", "BestDistance", or "BestBalance", limiting the final output to the corresponding single solution that provides the best value, respectively, for "Cost", "DistanceKm", or "BalanceMinutes".
IdleTimeSecond Default: 604800. Time to wait (in seconds) before an inactive session is automatically deleted.
InterimOutputChoice The interim output (at intervals of OutputInterval time), by default shows the complete set of solutions. With this key, however, you can limit the interim output to a single solution. The same values can be used as for FinalOutputChoice.
LocationPrecisionMetre Default: 1. This is a positive integer represents the precision EOS would use for input problem's locations. Less precision values mean that more adjacent locations might be considered as same location. Based on the LocationPrecisionMetre value, EOS is clustering problem's locations into clusters each with maximum size of LocationPrecisionMetre in meters. When EOS identify a group of geographic locations which can be located in a circle with diameter less than LocationPrecisionMetre value, all these geographic locations are represented by one of the group's locations; usually, the location in the centre is used to represent other group's locations.
MaxDailyJobsNumber Default: null. This is the maximum number of jobs allowed in the session per day. When missing or configured as null, EOS will not limit number of jobs.
OutputInterval Default: "15s". The time interval between interim outputs showing the latest collection of solutions.
PlanAllJobs Default: false.This specifies whether or not EOS will force plan all jobs and calculate penalties score for constraints violations.
RoutingService Default: "OSRM". Routing service which will be used to calculated driver-time matrices. One of the following values is possible: "OSRM", "HERE", "GEOMAP", "GEOMAP-ERS-OSM", "GEOMAP-ERS-HERE". Mapedits are supported by: "GEOMAP-ERS-OSM" and "GEOMAP-ERS-HERE"only.
MaximumDaysPlanningInTheFuture Default: 7. This controls how many days in the future EOS would plan, the value of 0 means that EOS would only plan for today whereas 1 means EOS would plan today and tomorrow. In other words, The value of n means EOS would plan up until the nth day in the future.
NoteLevel Default: null. When the note level is set in the input request, a new nested object called NoteLog will be populated in the output plans. The accepted value for this field is: WARNING.
PlanIncludeSlotInfo Default: false. Determines whether the EOS plan includes data on current slots. Applicable to plans retrieved via the GET /plan endpoint and, if configured, through webhook payloads.
SlotBookingCautionLevel Default: 100. This replaces the default caution level for all new slot reservations in the ongoing session. Its value ranges from 0 to 200, with 0 indicating the lowest level of caution and 200 representing the highest level of caution.
TimeZone Default: UTC. The IANA Time Zone of the plan.

Resources

Key Description
Depots Default:null. Specify a list of depots, for more info please check Depot Key/Value pairs. Note: there should always be at least one depot, except in the following case: when all jobs are Visits, and each vehicle has both StartLocationGeohash and EndLocationGeohash set.
Drivers Mandatory. Specify a list of drivers; at least one must be provided; for more info please check Driver Key/Value pairs. Note: a 'driver' in this context will not normally refer to an individual person. Instead, it is a collection of driver attributes that will be inherited by some of the vehicles (via the VehicleDriverMap - see below). For example, there might be two drivers, one named "EarlyShift" and one named "LateShift", holding the respective operating constraints.
Jobs Mandatory. Specify a list of job requests, each item has the format specified in Job Key/Value pairs. At least one job must be provided.
Vehicles Mandatory. Specify a list of vehicles. A vehicle is almost always a specific vehicle. For example, if the client has 25 vehicles available today, then there will be 25 vehicles in this array. At least one vehicle must be provided. For more info please refer to Vehicle Key/Value pairs.
VehicleDepotMap Default:null. This must be present, unless it is a rare case with no Depots provided (see above). This array defines the relationship between Vehicles and Depots, this is a list of mapping items defined in VehicleDepotMap Array. Normally there will be precisely one Vehicle/Depot pair for each vehicle. However it is possible for a vehicle to be mapped to multiple depots; this would mean that this vehicle is free to load, unload, or finish its route at any of these depots, irrespective of where it started its route.
VehicleDriverMap Default:null. Partially or fully defines the relationship between Vehicles and Drivers, this is a list of mapping items defined in VehicleDriverMap Array. Every vehicle will usually be mapped to precisely one driver. Meanwhile, because there may be several instances of each driver available (see Driver Key/Value pairs), one driver may be mapped to many vehicles. If this is is not present, drivers will be allocated to vehicles automatically; if it is present but only contains a partial map, then drivers will be allocated to the remaining vehicles. Automatic allocation of drivers will respect the Drivers' Availability constraints, and, if any, the Vehicles' DriverCharacteristics.
VehicleProfiles Mandatory. A list of vehicle types, giving a type name (e.g. "HGV", "minivan",...), a speed profile and some other data for each type VehicleProfiles Array. The list of types should cover each of the Vehicles in the list below.

EOS Plan

Schedule result has the following JSON format

{
  "EndDate": "2020-08-04",
  "RequestId": "4e085de4ba4def0f6c293a28f1e341a681d662f608428d84127db0dbc30ab3d5",
  "Result": "SCHEDULES",
  "Issues": [],
  "TimestampUnix": 1596465298,
  "StartDate": "2020-08-04",
  "Data": {
    "SolutionSet": [{
            "Objectives":   {
                    "BalanceSecond":        0,
                    "CarbonKg":     3.98804,
                    "Cost": 1451.3139999999999,
                    "DistanceKm":   398.804,
                    "OvertimeSecond":       1800,
                    "PlannedJobsNumber":    1,
                    "ShiftsNumber": 1,
                    "TotalTimeSecond":      23670,
                    "UnplannedJobsNumber":  1
            },
            "Schedule":     [{
                            "Actions":      [{
                                            "ActionType":   "SHIFTSTART",
                                            "Day":  1,
                                            "StartLocationGeohash": "u10q4r59",
                                            "StartLatLon":  [51.71837, -1.0475999],
                                            "StartTime":    "06:00:00",
                                            "Drivers":      ["Driver_1"]
                                    }, {
                                            "ActionType":   "BRIEF",
                                            "Day":  1,
                                            "StartLocationGeohash": "u10q4r59",
                                            "StartLatLon":  [51.71837, -1.0475999],
                                            "StartTime":    "06:00:00",
                                            "EndTime":      "06:15:00",
                                            "Drivers":      ["Driver_1"]
                                    }, {
                                            "ActionType":   "LOAD_UNLOAD",
                                            "Day":  1,
                                            "StartLocationGeohash": "u10q4r59",
                                            "StartLatLon":  [51.71837, -1.0475999],
                                            "StartTime":    "06:15:00",
                                            "EndTime":      "06:21:00",
                                            "Drivers":      ["Driver_1"],
                                            "Unload":       [],
                                            "Load": ["Job_1"]
                                    }, {
                                            "ActionType":   "TRAVEL",
                                            "Day":  1,
                                            "StartLocationGeohash": "u10q4r59",
                                            "EndLocationGeohash":   "gcp7b4v4",
                                            "StartLatLon":  [51.71837, -1.0475999],
                                            "EndLatLon":    [51.29964, 0.455261394],
                                            "StartTime":    "06:21:00",
                                            "EndTime":      "08:57:00",
                                            "DistanceKm":   199.402,
                                            "Drivers":      ["Driver_1"]
                                    }, {
                                            "ActionType":   "DELIVER",
                                            "Day":  1,
                                            "IdString":     "Job_1",
                                            "StartLocationGeohash": "gcp7b4v4",
                                            "StartLatLon":  [51.29964, 0.455261394],
                                            "StartTime":    "08:57:00",
                                            "EndTime":      "09:13:00",
                                            "Drivers":      ["Driver_1"]
                                    }, {
                                            "ActionType":   "TRAVEL",
                                            "Day":  1,
                                            "StartLocationGeohash": "gcp7b4v4",
                                            "EndLocationGeohash":   "u10q4r59",
                                            "StartLatLon":  [51.29964, 0.455261394],
                                            "EndLatLon":    [51.71837, -1.0475999],
                                            "StartTime":    "09:13:00",
                                            "EndTime":      "12:34:00",
                                            "DistanceKm":   199.402,
                                            "Drivers":      ["Driver_1"]
                                    }, {
                                            "ActionType":   "BREAK",
                                            "Day":  1,
                                            "StartTime":    "11:07:00",
                                            "EndTime":      "11:52:00",
                                            "Drivers":      ["Driver_1"]
                                    }, {
                                            "ActionType":   "SHIFTEND",
                                            "Day":  1,
                                            "StartLocationGeohash": "u10q4r59",
                                            "StartLatLon":  [51.71837, -1.0475999],
                                            "StartTime":    "12:34:00",
                                            "Drivers":      ["Driver_1"]
                                    }],
                            "VehicleId":    "Vehicle_1"
                    }],
            "UnplannedJobs":        []
    }],
    "ExecutionTimeSecond":  60
  }
}

EOS plans can be obtained using:

RESTful API call enables end-user to retrieve current plans on-demand. On the other hand, the WebSocket endpoint provides a mechanism to obtain plan updates automatically. Thus, the end-user doesn't have to keep polling EOS.

EOS WebSocket requires the SessionID as a parameter. The WebSocket client will receive updates on session plans as they evolve. Alternatively, it is possible to configure the WebSocket with both a SessionID and a PlanDate. In this case, the WebSocket client will receive plan updates on the given date only.

Please refer to the Examples Get Plan section for more details on WebSockets.

Data Key/value pairs associated with Schedule result

Key Description
SolutionSet An array of alternative solutions for the given routing problem, for more info please check Solution Object
shell python javascript