Basic Information

In this page, you will be able to learn about all data structures our service uses. Most of the structures are used to construct a problem, either to define an element (e.g Driver) or as an argument for the constraints (e.g TimeWindow). The rest describe the solution generated by the server, or are used in building rules and request mining. The parameter, type and description for each data structures are presented in the table, and those information can be used to construct the JSON object of a given type using the format:

{
  parameter : some value of the type,
  ...
}

For example, an object of type Line would be:

{
  "p1": {
    "x": 37.58203,
    "y": 126.39135
  },
  "p2": {
    "x": 38.10224,
    "y": 126.12778
  }
}

It should be noted that not all parameters in the table are required. Those parameter, if decided not necessary, should simply be left out as opposed to providing a "default value" (for example, placing empty array for an optional parameter of type Array).

Data Structures

Location

Parameter	Type	Description
x	Double	Required. An x coordinate of the location, or longitude.
y	Double	Required. A y coordinate of the location, or latitude.
id	String	Optional
labels	Array[String]	Optional. A set of strings that describes this location. Used for mining the rules.

Depot

Usually, depot is the location route starts and ends.

Parameter	Type	Description
id	String	Required
location	Location	Required. The location of this depot.

Capacity

Capacity contains a volume and weight. This structure is used both as a specification of a load and as a limit of drivers.

Parameter	Type	Description
data	Object	Required. An object with a key of either "Volume" or "Weight" and a value (Double) specifying the corresponding number.

Coordinate

Parameter	Type	Description
x	Double	Required.
y	Double	Required.

Line

Parameter	Type	Description
p1	Coordinate	Required. One endpoint of the line.
p2	Coordinate	Required. Another endpoint of the line.

Polygon

Parameter	Type	Description
points	Array[Coordinate]	Required. A set of points that comprises the polygon.

Time

Time represents the UNIX epoch in seconds.

Parameter	Type	Description
epoch	Long	Required.

Duration

The unit of Duration is also in seconds.

Parameter	Type	Description
seconds	Long	Required.

TimeWindow

Time window represents the specific times that an order needs to be fulfilled. The absence of "start" or "end" can be interpreted as "any time before" or "any time after" respectively.

Parameter	Type	Description
start	Time	Optional. The start time of the time window.
end	Time	Optional. The start time of the time window.

Task

The task is the smallest unit of work that needs to be carried out. Simply put, it is either delivery, pick up or service.

Parameter	Type	Description
id	String	Required.
jobId	String	Required. The ID of the job the task belongs to.
taskType	String	Required. The type of the task. Can be one of "Service", "PickUp", "Delivery" and "DepotDelivery".
location	Location	Required. The location of the task.
capacity	Capacity	Required. The capacity of the task.
taskDuration	Duration	Required. The duration of the task.
timeWindow	TimeWindow	Required. The time window that the task needs to be fulfilled.
difficulty	Int	Optional. The skill level required for the task.

Job

Job is a set of tasks with order condition. For example, if a job consists of picking up an item at A and delivering it to B, the first task must happen before the second task.

Parameter	Type	Description
id	String	Required.
tasks	Array[Task]	Required. An unordered set of tasks.
partialOrder	Array[Array[String]]	Required. An array of two task IDs, where those two task IDs are in an array. It defines the ordering requirements of the job.

Driver

A driver object can be thought of as a midpoint between the (physical) vehicle and the (physical) driver, and it contains attributes that would be more suitable for the vehicle object (maxCapacity). The design decision was made to not add an additional abstraction between vehicle and driver.

Parameter	Type	Description
id	String	Required.
maxCapacity	Capacity	Required. The maximum capacity that the vehicle can hold.
startLocation	Location	Optional. Sometimes, the vehicle's location might be different from its usual location (parking lot, depot, etc) when the routing request arrives. Its current location can be provided as startLocation in those situations.
endLocation	Location	Optional. Similar to the vehicle's startLocation, it is not always the case that the vehicle should be returned to specific location (depot, for example). Its end location can be provided in those situations.
startTime	Time	Required. The time in epoch when the driver should start executing the tasks.
endTime	Time	Required. The time in epoch when the driver should be done with the tasks.
skillLevel	Int	Optional. In real world, some drivers are more skilled than others in terms of task processing speed, driving skills, etc. The skillLevel represents the driver's proficiency and is used to model the tasks / jobs that only certain drivers can perform. The default value is 0.
vehicleFeatures	Array[String]	Optional. The feature of the vehicle. One valid example would be "2 ton truck". The values in this field are used to model the restrictions on specific jobs / tasks. See zone-related constraints for more information. By default, the vehicle does not have any feature.
maxWaitTime	Duration	Optional. The maximum amount of time that the driver waits if he / she arrives at the task location earlier than the specified time window.

Route

A route is a plan for a single driver. It is an assignment of jobs, which in turn is an ordered list of tasks.

Parameter	Type	Description
id	String	Optional.
driver	Driver	Required. The driver carrying out the route.
jobs	Array[Job]	Required. The jobs in the route.
tasks	Array[Task]	Required. The ordered array of tasks in the route.
gis	String	Required. The type of GIS to use to calculate task service times and distance.