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.

Unassigned Stops

Unassigned Stops are a type of stop that are not yet assigned to any Plan. They can be imported in bulk to the API, and then they can be assigned to Plans by a dispatcher using the Web UI.

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.

Operations

Operations are resources used to keep track of long-running operations in Circuit API.

Currently, there is only one type of long-running operation, which is the plan_optimization.

The plan_optimization operation stores information about and optimization operation on a Plan. This is necessary because plan optimizations can take a long time to finish depending on the amount of stops a plan has and how they are geographically distributed.

With operations, we can keep an asynchronous long-running operation running in the Circuit infrastructure while users of the API can check on their status periodically by using polling.