API Reference#

Tarot Routing - Route Optimisation API

Request#

RoutingProblem#

RoutingProblem: JSON Object#

A RoutingObject is the body of the request send to the Route Optimisation API endpoint.

Parameters:

drivers (list[Driver]) – The Drivers to perform the Jobs
jobs (list[Job]) – The Jobs to be optimised
settings (Settings) – The Settings under which the optimiser will run

Minimal Example

{
  "drivers": [
    {
      "uid": "drvid1",
      "shift_start": 8,
      "shift_end": 17,
      "location": {"lat": -33.867798, "lon": 151.166256}
    }
  ],
  "jobs": [
    {
      "uid": "uid1",
      "duration": 2,
      "location": {"lat": -33.849489, "lon": 151.127482}
    },
    {
      "uid": "uid2",
      "duration": 2,
      "location": {"lat": -33.880661, "lon": 151.183096}
    },
    {
      "uid": "uid3",
      "duration": 2,
      "location": {"lat": -33.913168, "lon": 151.262267}
    }
  ],
  "settings": {}
}

Driver#

Driver: JSON Object#

A Driver represents a driver, their vehicle, or a theoretical run.

Parameters:

uid (str) –

A Unique Identifier for this Driver. No two Drivers may have the same UID
shift_start (float) –

The earliest time this Driver may begin their shift. Time of day as float (e.g. 8.5) in 24h time
shift_end (float) –

The earliest time this Driver may begin their shift. Time of day as float (e.g. 8.5) in 24h time
location (Location) –

Where the Driver begins their run.
end_location (Location) –
[optional, default=driver.location]

Where the Driver ends their run. Ignored if end_anywhere=True. Learn More…
end_anywhere (bool) –
[optional, default=False]

Optimise allowing this Driver to finish at her last Job (instead of returning to the start location or to the end_location). Learn More…
capacity (int or str) –
[optional]

Set the capacity of the vehicle. The algorithm compares the total size of all Jobs in this Driver’s run to the capacity of the vehicle. Simple Capacity can be expressed as an integer. For advanced use cases, see Capacity.
spec_type (str) –
[optional]

A Job can only be served by a Driver that has at least one spec_type in common. Learn how to use Types
territories (str) –
[optional]

A Job can only be served by a Driver with at least one of its territories in common. Learn how to use Territories.
speed_multiplier (float) –
[optional, default=1]

Adjust the driving speed of this Driver. A value of 0.5 means that this Driver will drive half as fast as normal. A value of 1.2 means that this Driver will drive 20% faster than normal.
lunch_time (float) –
[optional]

The earliest time that a Driver can start their lunch break. Time is represented as decimal 24h time. So a lunch break starting at 1:15pm is expressed as 13.25
lunch_duration (float) –
[optional]

The duration in minutes of the Driver’s lunch break
lunch_latest_start (float) –
[optional, default=lunch_time + lunch_duration/60]

The latest time the Driver’s lunch break my start. To force an exact lunch time, set job.lunch_latest_start = job.lunch_time
range_limit (float) –
[optional, default=null]

Limit the number of KMs the Driver can drive on their route (e.g. for electric vehicle range limits)
costs (Costs) –
[optional, default=null]

The costs (per km, per hour, per job, and per run) associated with this Driver.

If Settings.optimisation_objective = "cost" you must provide costs for every Driver.

For all other optimisation objectives, costs are ignored.

Learn More…

Minimal Example

{
  "uid": "unique_driver_id_1",
  "location": {"lat": -33.867798, "lon": 151.166256},
  "shift_start": 9.5,
  "shift_end": 18.5
}

Standard Example

{
  "uid": "drvid1",
  "location": {
    "lat": -33.84948962,
    "lon": 151.1274823
  },
  "shift_start": 9.5,
  "shift_end": 18.5,
  "speed_multiplier": 0.8,
  "lunch_time": 12.5,
  "lunch_duration": 45,
  "spec_type": "plumber,electrician",
  "capacity": 25
}

Job#

Job: JSON Object#

Jobs represent tasks, delivery points, customers etc.

Parameters:

uid (str) – A Unique Identifier for this Job. No two Jobs may have the same UID
location (Location) – Where the Job is
duration (float) – The number of minutes the Driver must spend at this Job. Include parking, doing the Job, getting back to the vehicle, etc. Often called the service time
arrive_after (float) – [optional] The earliest time the Driver may begin this Job. Time of day as float (e.g. 13.75) in 24h time
leave_by (float) – [optional] The latest time the Driver may finish working on this Job. Time of day as float (e.g. 15.5) in 24h time
size (float or str) – [optional] The cumulative size s of Jobs are matched against each Driver's capacity to ensure that a Driver/vehicle does not exceed her vehicle’s capacity. Units can be whatever syou wish, but must be consistent between all Job's sizes and Driver's capacities. If ANY Job has a size, ALL Drivers must have a capacity. For advanced use cases, see Capacity.
spec_type (str) – [optional] A Job can only be served by a Driver that has at least one spec_type in common. Learn how to use Types.
territories (str) – [optional] A Job can only be served by a Driver with at least one of its territories in common. Learn how to use Territories.
priority (bool) – [optional, default=false] If some Jobs are more important than others, mark them as priority=true. In Scenarios where not all Jobs can be served by your available Driver`s, these :py:data:`Jobs will be served, even if several others are not.
pickup_from (str) – [optional] This creates a Pickup and Delivery constraint by referring to the uid of another Job. Learn about Pickup Delivery.
pd_interval_max (bool) – [optional] Sets the maximum time in minutes allowed between a Pickup Delivery pair of jobs. It should be set on the Delivery Job only. Specifically, it sets a constraint on the Job ETAs, equivalent to delivery_job.eta - pickup_job.eta < pd_interval_max
exclude_period_start (float) – [optional] The start of a negative time window. For example, if you don’t want to visit a Job during their lunch break, you could set an exclude_period_start and exclude_period_end for it. Time of day as float (e.g. 13.75) in 24h time
exclude_period_end (float) – [optional] The end of a negative time window. For example, if you don’t want to visit a Job during their lunch break, you could set an exclude_period_start and exclude_period_end for it. Time of day as float (e.g. 13.75) in 24h time
immovable (bool) – beta [optional, default=false] If you are re-optimising a run in real-time (i.e. after the Driver has already started performing the route), and this Job has already been served, you can prevent it from being moved during the optimisation by setting job.immovable=true. This parameter may only be used if initial_runs are provided.

Minimal Example

{
  "uid": "unique_job_id_1",
  "duration": 10,
  "location": {"lat": -33.849489, "lon": 151.127482}
}

Standard Example

{
  "uid": "unique_job_id_2",
  "duration": 10,
  "arrive_after": 10,
  "leave_by": 16.5,
  "location": {
    "lat": -33.84948962,
    "lon": 151.1274823
  },
}

Location#

Location: JSON Object#

A Location defines the geographical position of a Driver or Job

Parameters:

lat (float) – Latitude
lon (float) – Longitude

Example

{
  "lat": -33.88066125,
  "lon": 151.1830961
}

Settings#

Settings: JSON Object#

Settings convey parameters which affect the way that the optimisation algorithm runs.

Parameters:

allocate_fairly (bool) –
[optional, default=false]

If allocate_fairly=true, the algorithm will attempt to allocate Jobs to Drivers

in a way that is fair. This means that the algorithm will attempt to allocate roughly the same number of Jobs to each Driver.

Learn more about Fairness.
quick_opt (bool) –
[optional, default=true]

Should the algorithm stop once it reaches a local minimum to get a reasonably optimal result quickly?

If True: The algorithm will stop fairly quickly once it has found a reasonably good solution.

Use quick_opt=true when it is important to get a solution as fast as possible (e.g. in real time optimisations).

If False: The algorithm will run until it reaches the improvement_threshold_per_second or the max_opt_time, whichever comes first.

Use quick_opt=false when it is important to reach a very optimal solution, but be sure to set max_opt_time and/or improvement_threshold_per_second

Learn More…
max_opt_time (int) –
[optional, default=450]

The maximum number of seconds the algorithm is allowed to spend optimising.

Learn More…
improvement_threshold_per_second (float) –
[optional, default=0.00005]

The algorithm periodically measures the percentage improvement in the result vs time.

If the improvement is less than this threshold, the result is returned instead of continuing the search.

Set it to zero for no improvement threshold

Learn More…
min_time_aboard (bool) –
[optional, default=false]

Only applies to Pickup Delivery problems.

If min_time_aboard=true, the optimiser will try to minimise the interval between a Pickup and its related Delivery

Learn More…
walkable_threshold (int) –
[optional, default=0] Seconds

Determines whether to bias neighbouring Jobs to be served consecutively or not.
- Setting to 0 disables the bias.
- Setting to 1 means that only Jobs at the exact same location are biased to be served together.
- Setting to 30 means that any Jobs within 30s drive of each other will be biased to be served consecutively.
Learn More…
optimisation_objective (str) –
[optional, default="time"] One of time, cost, distance

The objective of the optimisation.

If time, the algorithm will try to minimise the total time taken to complete all Jobs.

If cost, the algorithm will try to minimise the total cost of completing all Jobs.

If distance, the algorithm will try to minimise the total distance driven to complete all Jobs.

Learn More…

Minimal Example

{}

Standard Example

{
    "allocate_fairly": true,
    "quick_opt": false,
    "max_opt_time": 120,
}

Costs#

Costs: JSON Object#

Costs are considered when Settings.optimisation_objective = "cost" and represent costs to be minimised by the optimiser. They can be in any “currency” you like (Dollars, Euros, Points, etc), but the currency should be consistent across all costs.

If you set Settings.optimisation_objective = "cost", you must provide costs for every Driver.

Parameters:

km (float) –
[optional, default=0]

The cost per kilometre driven by this Driver.
hour (float) –
[optional, default=0]

The cost per hour that this Driver is working.

This includes time stopped at Jobs, waiting for a time window, breaks, etc.
job (float) –
[optional, default=0]

The cost per Job that this Driver performs.
run (float) –
[optional, default=0]

The cost for this Driver being active (i.e. serving any Jobs).

Having a per run cost is useful for minimising the total number of drivers used.

Settings different per_run costs for each Driver will also encourage the optimiser

to favour certain Drivers over others.

Minimal Example

{}

Standard Example

{
    "km": 0.20,
    "hour": 12.00,
    "job": 7.00,
    "run": 150.00,
}

Response#

RoutingSolution#

RoutingSolution: JSON Object#

The API response contains one RoutingSolution.

Parameters:

runs (List[Run]) – A list of Runs
unserved_jobs (List[Job]) – A list of Jobs which the optimiser could not find a way to visit.

Run#

Run: JSON Object#

Parameters:

driver (Driver) – The Run’s Driver
jobs (List[SolutionJobs]) – A list of SolutionJobs (if any) in the sequence they should be driven.

SolutionJob#

SolutionJob: JSON Object#

Each SolutionJob is identical to the Job which you sent to the optimiser, but it has a few extra fields to help communicate the solution to you.

Parameters:

run (int) – A 1-based index indicating which run this Job is planned in. Unserved Jobs have run=null.
seq (int) – Indicates this Job’s sequence within the Run. Unserved Jobs have seq=null.
eta (str) – Indicates the Estimated Time of Arrival at that Job as a human-readable string HH:MM:SS. E.g. 2:30pm is represented as 14:30:00. Unserved Jobs have eta=null.
decimal_eta (float) – Indicates the Estimated Time of Arrival at that Job as a float. E.g. 2:30pm is represented as 14.5. Unserved Jobs have decimal_eta=null.
etd (str) – Indicates the Estimated Time of Departure from that Job as a human-readable string HH:MM:SS. E.g. 2:30pm is represented as 14:30:00. Unserved Jobs have etd=null.
decimal_etd (float) – Indicates the Estimated Time of Departure from that Job as a float. E.g. 2:30pm is represented as 14.5. Unserved Jobs have decimal_eta=null.

API Reference

Contents

API Reference#

Request#

RoutingProblem#

Driver#

Job#

Location#

Settings#

Costs#

Response#

RoutingSolution#

Run#

SolutionJob#