This page provides JSON schema for the data structures used in the engine.

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

ParameterTypeDescription
xDoubleRequired. An x coordinate of the location, or longitude.
yDoubleRequired. A y coordinate of the location, or latitude.
idStringOptional
labelsArray[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.

ParameterTypeDescription
idStringRequired
locationLocationRequired. 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.

ParameterTypeDescription
dataObjectRequired. An object with a key of either "Volume" or "Weight" and a value (Double) specifying the corresponding number.

Coordinate

ParameterTypeDescription
xDoubleRequired.
yDoubleRequired.

Line

ParameterTypeDescription
p1CoordinateRequired. One endpoint of the line.
p2CoordinateRequired. Another endpoint of the line.

Polygon

ParameterTypeDescription
pointsArray[Coordinate]Required. A set of points that comprises the polygon.

Time

Time represents the UNIX epoch in seconds.

ParameterTypeDescription
epochLongRequired.

Duration

The unit of Duration is also in seconds.

ParameterTypeDescription
secondsLongRequired.

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.

ParameterTypeDescription
startTimeOptional. The start time of the time window.
endTimeOptional. 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.

ParameterTypeDescription
idStringRequired.
jobIdStringRequired. The ID of the job the task belongs to.
taskTypeStringRequired. The type of the task. Can be one of "Service", "PickUp", "Delivery" and "DepotDelivery".
locationLocationRequired. The location of the task.
capacityCapacityRequired. The capacity of the task.
taskDurationDurationRequired. The duration of the task.
timeWindowTimeWindowRequired. The time window that the task needs to be fulfilled.
difficultyIntOptional. 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.

ParameterTypeDescription
idStringRequired.
tasksArray[Task]Required. An unordered set of tasks.
partialOrderArray[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.

ParameterTypeDescription
idStringRequired.
maxCapacityCapacityRequired. The maximum capacity that the vehicle can hold.
startLocationLocationOptional. 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.
endLocationLocationOptional. 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.
startTimeTimeRequired. The time in epoch when the driver should start executing the tasks.
endTimeTimeRequired. The time in epoch when the driver should be done with the tasks.
skillLevelIntOptional. 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.
vehicleFeaturesArray[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.
maxWaitTimeDurationOptional. 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.

ParameterTypeDescription
idStringOptional.
driverDriverRequired. The driver carrying out the route.
jobsArray[Job]Required. The jobs in the route.
tasksArray[Task]Required. The ordered array of tasks in the route.
gisStringRequired. The type of GIS to use to calculate task service times and distance.