Models Descriptions

This page describes each of the Models in the API version v0.2b

Plan and Route

The Circuit API has two different models to represent what activities are to be done by drivers, Plans and Routes.

Plan

A Plan is a collection of Stops that shall be assigned to Drivers on a specific day, and this Plan can be related to a Depot.

When a Plan is optimized by a dispatcher, then it will create a number of related Routes (notice that Routes are only related to a Plan, but not hierarchically grouped under them), these Routes are then each assigned to a Driver.

In the current version of the API, a Plan can only be edited before it is optimized, after that no changes to it, or its related or child resources are allowed, and it becomes read-only. To assist in checking whether the Plan is still able to be edited, or have new Stops added to it, just check the writable property on it.

Route

Routes, as described in the previous section, only exist after optimization of a Plan. A Route can have a related Driver and is a representation of which Stops a Driver will be making.

Stops will only have some information after the Plan is optimized, and thus they become related to a Route, so information such as ETA (Estimated Time of Arrival), distance of travel, duration of travel, and stop order, will only become available after optimization.

In the current version of the API a Route is a read-only resource.

Stops

Stops are a resource in the Circuit API that is always hierarchically related to a Plan, and may also be in a N:1 relationship with a Route after said Plan is optimized.

Stops are the resources that represent what activities a Driver should be doing, they contain information on an address, and whether the activity on this address is a pickup or a delivery, among other important information, such as when said activity is expected to happen (ETA), the order this activity has on the overall Route a Driver needs to make, the distance between the earlier stop and the current one, among others.

Stops cannot be added to a Plan or edited if their parent Plan is no longer writable.

Depots

Depots are read-only resources that represent what Depots your team has configured in the web-ui. You can associate a Plan to a Depot to inherit the settings of that depot, such as starting and end addresses of the optimized routes.

Drivers

Drivers are read-only resources that represent any members of your team that have the driver role assigned to them. A set of Drivers can be assigned to a Plan, so they are considered for assignment to Routes when said Plan is optimized.