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

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

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…

Minimal Example

{}

Standard Example

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



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

  • jobs (List[SolutionJobs]) – A list of (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.