{"_id":"573545a3afab4417007239c5","__v":19,"category":{"_id":"5706099c21cfed0e00e8c60f","project":"5706099c21cfed0e00e8c60b","version":"5706099c21cfed0e00e8c60e","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-04-07T07:17:48.833Z","from_sync":false,"order":0,"slug":"documentation","title":"Introduction"},"user":"570614bde2df830e00d52774","version":{"_id":"5706099c21cfed0e00e8c60e","hasDoc":true,"project":"5706099c21cfed0e00e8c60b","__v":6,"hasReference":true,"createdAt":"2016-04-07T07:17:48.808Z","releaseDate":"2016-04-07T07:17:48.808Z","categories":["5706099c21cfed0e00e8c60f","573548f4afab4417007239cf","57354970fc5f1e0e001a463c","573549791f16241700c89fc9","57441052583f470e000a7947","57a068f90c933e0e00249bae"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.17","version":"1.0.17"},"parentDoc":null,"project":"5706099c21cfed0e00e8c60b","githubsync":"","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-05-13T03:10:27.795Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"# Basic Information\nIn 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  parameter : some value of the type,\\n  ...\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nFor example, an object of type Line would be:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"p1\\\": {\\n    \\\"x\\\": 37.58203,\\n    \\\"y\\\": 126.39135\\n  },\\n  \\\"p2\\\": {\\n    \\\"x\\\": 38.10224,\\n    \\\"y\\\": 126.12778\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nIt 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).\n\n# Data Structures\n## Location\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"x\",\n    \"0-1\": \"Double\",\n    \"1-0\": \"y\",\n    \"2-0\": \"id\",\n    \"3-0\": \"labels\",\n    \"1-1\": \"Double\",\n    \"2-1\": \"String\",\n    \"3-1\": \"Array[String]\",\n    \"0-2\": \"Required. An x coordinate of the location, or longitude.\",\n    \"1-2\": \"Required. A y coordinate of the location, or latitude.\",\n    \"2-2\": \"Optional\",\n    \"3-2\": \"Optional. A set of strings that describes this location. Used for mining the rules.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n## Depot\nUsually, depot is the location route starts and ends.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"id\",\n    \"0-1\": \"String\",\n    \"0-2\": \"Required\",\n    \"1-0\": \"location\",\n    \"1-1\": \"Location\",\n    \"1-2\": \"Required. The location of this depot.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n## Capacity\nCapacity contains a volume and weight. This structure is used both as a specification of a load and as a limit of drivers. \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"data\",\n    \"0-1\": \"Object\",\n    \"0-2\": \"Required. An object with a key of either \\\"Volume\\\" or \\\"Weight\\\" and a value (Double) specifying the corresponding number.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n## Coordinate\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"x\",\n    \"0-1\": \"Double\",\n    \"0-2\": \"Required.\",\n    \"1-0\": \"y\",\n    \"1-1\": \"Double\",\n    \"1-2\": \"Required.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n## Line\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"p1\",\n    \"0-1\": \"Coordinate\",\n    \"0-2\": \"Required. One endpoint of the line.\",\n    \"1-0\": \"p2\",\n    \"1-1\": \"Coordinate\",\n    \"1-2\": \"Required. Another endpoint of the line.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n## Polygon\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"points\",\n    \"0-1\": \"Array[Coordinate]\",\n    \"0-2\": \"Required. A set of points that comprises the polygon.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n## Time\nTime represents the UNIX epoch in seconds.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"epoch\",\n    \"0-1\": \"Long\",\n    \"0-2\": \"Required.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n## Duration\nThe unit of Duration is also in seconds.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"seconds\",\n    \"0-1\": \"Long\",\n    \"0-2\": \"Required.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n## TimeWindow\nTime 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.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"start\",\n    \"1-0\": \"end\",\n    \"0-1\": \"Time\",\n    \"0-2\": \"Optional. The start time of the time window.\",\n    \"1-1\": \"Time\",\n    \"1-2\": \"Optional. The start time of the time window.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n## Task\nThe task is the smallest unit of work that needs to be carried out. Simply put, it is either delivery, pick up or service.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"id\",\n    \"0-1\": \"String\",\n    \"0-2\": \"Required.\",\n    \"1-0\": \"jobId\",\n    \"1-1\": \"String\",\n    \"1-2\": \"Required. The ID of the job the task belongs to.\",\n    \"2-0\": \"taskType\",\n    \"2-1\": \"String\",\n    \"2-2\": \"Required. The type of the task. Can be one of \\\"Service\\\", \\\"PickUp\\\", \\\"Delivery\\\" and \\\"DepotDelivery\\\".\",\n    \"3-0\": \"location\",\n    \"3-1\": \"Location\",\n    \"3-2\": \"Required. The location of the task.\",\n    \"4-0\": \"capacity\",\n    \"4-1\": \"Capacity\",\n    \"4-2\": \"Required. The capacity of the task.\",\n    \"5-0\": \"taskDuration\",\n    \"5-1\": \"Duration\",\n    \"5-2\": \"Required. The duration of the task.\",\n    \"6-0\": \"timeWindow\",\n    \"6-1\": \"TimeWindow\",\n    \"6-2\": \"Required. The time window that the task needs to be fulfilled.\",\n    \"7-0\": \"difficulty\",\n    \"7-1\": \"Int\",\n    \"7-2\": \"Optional. The skill level required for the task.\"\n  },\n  \"cols\": 3,\n  \"rows\": 8\n}\n[/block]\n## Job\nJob 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.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"id\",\n    \"0-1\": \"String\",\n    \"0-2\": \"Required.\",\n    \"1-0\": \"tasks\",\n    \"1-1\": \"Array[Task]\",\n    \"1-2\": \"Required. An unordered set of tasks.\",\n    \"2-0\": \"partialOrder\",\n    \"2-1\": \"Array[Array[String]]\",\n    \"2-2\": \"Required. An array of two task IDs, where those two task IDs are in an array. It defines the ordering requirements of the job.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n## Driver\nA 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.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"id\",\n    \"0-1\": \"String\",\n    \"0-2\": \"Required.\",\n    \"1-0\": \"maxCapacity\",\n    \"1-1\": \"Capacity\",\n    \"1-2\": \"Required. The maximum capacity that the vehicle can hold.\",\n    \"2-0\": \"startLocation\",\n    \"2-1\": \"Location\",\n    \"2-2\": \"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.\",\n    \"3-0\": \"endLocation\",\n    \"3-1\": \"Location\",\n    \"3-2\": \"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.\",\n    \"4-0\": \"startTime\",\n    \"4-1\": \"Time\",\n    \"4-2\": \"Required. The time in epoch when the driver should start executing the tasks.\",\n    \"5-0\": \"endTime\",\n    \"5-1\": \"Time\",\n    \"5-2\": \"Required. The time in epoch when the driver should be done with the tasks.\",\n    \"6-0\": \"skillLevel\",\n    \"6-1\": \"Int\",\n    \"6-2\": \"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.\",\n    \"7-0\": \"vehicleFeatures\",\n    \"7-1\": \"Array[String]\",\n    \"7-2\": \"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.\",\n    \"8-0\": \"maxWaitTime\",\n    \"8-1\": \"Duration\",\n    \"8-2\": \"Optional. The maximum amount of time that the driver waits if he / she arrives at the task location earlier than the specified time window.\"\n  },\n  \"cols\": 3,\n  \"rows\": 9\n}\n[/block]\n## Route\nA route is a plan for a single driver. It is an assignment of jobs, which in turn is an ordered list of tasks.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"1-0\": \"driver\",\n    \"1-1\": \"Driver\",\n    \"1-2\": \"Required. The driver carrying out the route.\",\n    \"2-0\": \"jobs\",\n    \"2-1\": \"Array[Job]\",\n    \"2-2\": \"Required. The jobs in the route.\",\n    \"3-0\": \"tasks\",\n    \"3-1\": \"Array[Task]\",\n    \"3-2\": \"Required. The ordered array of tasks in the route.\",\n    \"4-0\": \"gis\",\n    \"4-1\": \"String\",\n    \"4-2\": \"Required. The type of GIS to use  to calculate task service times and distance.\",\n    \"0-0\": \"id\",\n    \"0-1\": \"String\",\n    \"0-2\": \"Optional.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]","excerpt":"This page provides JSON schema for the data structures used in the engine.","slug":"data-schema","type":"basic","title":"Data Schema"}

Data Schema

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: [block:code] { "codes": [ { "code": "{\n parameter : some value of the type,\n ...\n}", "language": "json" } ] } [/block] For example, an object of type Line would be: [block:code] { "codes": [ { "code": "{\n \"p1\": {\n \"x\": 37.58203,\n \"y\": 126.39135\n },\n \"p2\": {\n \"x\": 38.10224,\n \"y\": 126.12778\n }\n}", "language": "json" } ] } [/block] 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 [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "x", "0-1": "Double", "1-0": "y", "2-0": "id", "3-0": "labels", "1-1": "Double", "2-1": "String", "3-1": "Array[String]", "0-2": "Required. An x coordinate of the location, or longitude.", "1-2": "Required. A y coordinate of the location, or latitude.", "2-2": "Optional", "3-2": "Optional. A set of strings that describes this location. Used for mining the rules." }, "cols": 3, "rows": 4 } [/block] ## Depot Usually, depot is the location route starts and ends. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "id", "0-1": "String", "0-2": "Required", "1-0": "location", "1-1": "Location", "1-2": "Required. The location of this depot." }, "cols": 3, "rows": 2 } [/block] ## Capacity Capacity contains a volume and weight. This structure is used both as a specification of a load and as a limit of drivers. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "data", "0-1": "Object", "0-2": "Required. An object with a key of either \"Volume\" or \"Weight\" and a value (Double) specifying the corresponding number." }, "cols": 3, "rows": 1 } [/block] ## Coordinate [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "x", "0-1": "Double", "0-2": "Required.", "1-0": "y", "1-1": "Double", "1-2": "Required." }, "cols": 3, "rows": 2 } [/block] ## Line [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "p1", "0-1": "Coordinate", "0-2": "Required. One endpoint of the line.", "1-0": "p2", "1-1": "Coordinate", "1-2": "Required. Another endpoint of the line." }, "cols": 3, "rows": 2 } [/block] ## Polygon [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "points", "0-1": "Array[Coordinate]", "0-2": "Required. A set of points that comprises the polygon." }, "cols": 3, "rows": 1 } [/block] ## Time Time represents the UNIX epoch in seconds. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "epoch", "0-1": "Long", "0-2": "Required." }, "cols": 3, "rows": 1 } [/block] ## Duration The unit of Duration is also in seconds. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "seconds", "0-1": "Long", "0-2": "Required." }, "cols": 3, "rows": 1 } [/block] ## 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. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "start", "1-0": "end", "0-1": "Time", "0-2": "Optional. The start time of the time window.", "1-1": "Time", "1-2": "Optional. The start time of the time window." }, "cols": 3, "rows": 2 } [/block] ## 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. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "id", "0-1": "String", "0-2": "Required.", "1-0": "jobId", "1-1": "String", "1-2": "Required. The ID of the job the task belongs to.", "2-0": "taskType", "2-1": "String", "2-2": "Required. The type of the task. Can be one of \"Service\", \"PickUp\", \"Delivery\" and \"DepotDelivery\".", "3-0": "location", "3-1": "Location", "3-2": "Required. The location of the task.", "4-0": "capacity", "4-1": "Capacity", "4-2": "Required. The capacity of the task.", "5-0": "taskDuration", "5-1": "Duration", "5-2": "Required. The duration of the task.", "6-0": "timeWindow", "6-1": "TimeWindow", "6-2": "Required. The time window that the task needs to be fulfilled.", "7-0": "difficulty", "7-1": "Int", "7-2": "Optional. The skill level required for the task." }, "cols": 3, "rows": 8 } [/block] ## 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. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "id", "0-1": "String", "0-2": "Required.", "1-0": "tasks", "1-1": "Array[Task]", "1-2": "Required. An unordered set of tasks.", "2-0": "partialOrder", "2-1": "Array[Array[String]]", "2-2": "Required. An array of two task IDs, where those two task IDs are in an array. It defines the ordering requirements of the job." }, "cols": 3, "rows": 3 } [/block] ## 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. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "id", "0-1": "String", "0-2": "Required.", "1-0": "maxCapacity", "1-1": "Capacity", "1-2": "Required. The maximum capacity that the vehicle can hold.", "2-0": "startLocation", "2-1": "Location", "2-2": "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.", "3-0": "endLocation", "3-1": "Location", "3-2": "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.", "4-0": "startTime", "4-1": "Time", "4-2": "Required. The time in epoch when the driver should start executing the tasks.", "5-0": "endTime", "5-1": "Time", "5-2": "Required. The time in epoch when the driver should be done with the tasks.", "6-0": "skillLevel", "6-1": "Int", "6-2": "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.", "7-0": "vehicleFeatures", "7-1": "Array[String]", "7-2": "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.", "8-0": "maxWaitTime", "8-1": "Duration", "8-2": "Optional. The maximum amount of time that the driver waits if he / she arrives at the task location earlier than the specified time window." }, "cols": 3, "rows": 9 } [/block] ## 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. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "1-0": "driver", "1-1": "Driver", "1-2": "Required. The driver carrying out the route.", "2-0": "jobs", "2-1": "Array[Job]", "2-2": "Required. The jobs in the route.", "3-0": "tasks", "3-1": "Array[Task]", "3-2": "Required. The ordered array of tasks in the route.", "4-0": "gis", "4-1": "String", "4-2": "Required. The type of GIS to use to calculate task service times and distance.", "0-0": "id", "0-1": "String", "0-2": "Optional." }, "cols": 3, "rows": 5 } [/block]