Plan Schema

Model

Plan

Plan = object

The plan data. All plans in the API will have this format.

Description

A plan is a collection of stops and drivers that when optimized will produce routes. A plan can be optimized multiple times and each optimization will produce a set of routes. A plan can also be distributed to drivers, which will produce a set of routes that are associated with drivers.

For your convenience you can check if a plan is editable using the normal plan APIs by checking the writable property. If it is false, you will need to use the Live Plan APIs to edit this plan.

Example

{
  "id": "plans/zeOCJaJCzZhpKVCVAC9o",
  "title": "Tue, Nov 22 Route 1",
  "starts": {
    "day": 22,
    "month": 11,
    "year": 2022,
  },
  "drivers": [
    "drivers/w8ZaNn3e5ZA8EQSABtca",
  ],
  "routes": [
    "routes/gjaqksJIa26qGPzsgBXT",
  ],
  "depot": "depots/zeOCJaJCzZhpKVCVAC9o",
  "optimization": 'optimized',
  "distributed": true,
  "writable": false,
}

Properties

Property	Type	Description
id	PlanId	This plan's unique identifier in the API. this can be used directly in the URL to operate on this plan.
title	string	The name of the plan. This is a human-readable name that is displayed in the UI.
starts	Date	The day this plan starts at.
drivers	DriverId[]	The drivers that are part of this plan. See Driver
depot	DepotId | null	The depot that this plan is for. See Depot
routes	RouteId[]	The routes this plan has. Note that you cannot operate on routes directly via the API in this version. See Route
optimization	"creating" | "editing" | "preview" | "optimized" | "optimizing" | null	The current optimization state of the plan. creating: The plan is in draft mode and not yet optimized. editing: The plan has been optimized and is currently being edited again. preview: The plan has been edited and reoptimized, but its changes have not been saved yet. optimizing: The plan is currently being optimized. optimized: The plan has been optimized and is not being edited.
distributed	boolean	Whether the plan was distributed to drivers.
writable	boolean	Whether this plan can be edited via the normal plan API or not. If this is false, you will need to use the Live Plan APIs to edit this plan.
routeOverrides	PlanRouteOverrides | null	Settings for this plan to override default route configurations.

Identifier

PlanId

PlanId = `plans/${string}`

A plan id is a string that is unique for a plan. It is used to identify the plan in the API.

Example

"plans/0xBYy4MYt4piMCSQEsts"

Fields

Date

Date = object

A Date is an object representing a day in the year.

Example

{
  "year": 2023,
  "month": 2,
  "day": 1
}

Properties

Property	Type
year	number
month	number
day	number

---

PlanRouteOverrides

PlanRouteOverrides = object

Settings for this plan to override default route configurations. All settings are optional and default to team's settings.

Properties

Property	Type	Description
startTime	TimeOfDay | null	The time of day that the Driver starts working. When null, the start time configured for the Depot will be taken into consideration when optimizing plans and distributing routes to drivers.
endTime	TimeOfDay | null	The time of day that the Driver finishes working. When null, the end time configured for the Depot will be taken into consideration when optimizing plans and distributing routes to drivers.
startAddress	StopAddress | null	A complete address to the location where the driver must always begin at. Optional. If null the start location of routes will be the Depot associated with the route assigned to the driver.
endAddress	StopAddress | null	A complete address to the location where the driver must always end at. Optional. If null the end location of routes will be the end location of the Depot associated with the route assigned to the driver or the driver's start location if "return to start location" is set.
maxStops	number | null	The maximum number of stops the driver must have per route. Optional. If null, the Depot's maximum number of stops per driver will be used instead.
drivingSpeed	RelativeSpeed | null	How fast the driver drives from stop to stop, compared to the average speed all drivers usually drive. This value defaults to "average" and if specified as "slower" or "faster", it will be taken into consideration when optimizing routes.
deliverySpeed	RelativeSpeed | null	How fast the driver completes deliveries, compared to the average of all drivers. This value defaults to "average" and if specified as "slower" or "faster", it will be taken into consideration when optimizing routes.
vehicleType	VehicleType | null	The vehicle type the driver uses. It may affect optimization, as some paths are available to certain vehicles but not to others.
optimizationSettings	OptimizationSettings	Optimization settings for the plan.

---

OptimizationSettings

OptimizationSettings = object

Configures the optimization settings for routes.

Properties

Property	Type	Description
objective	OptimizationObjective	The primary optimization objective.
subObjective?	OptimizationSubObjective | null	The secondary optimization objective.

---

OptimizationObjective

OptimizationObjective = "minimize_drivers" | "distribute_services"

The primary optimization objective.

---

OptimizationSubObjective

OptimizationSubObjective = "equalize_workload" | "equalize_time" | "maximize_efficiency"

The secondary optimization objective.