The Workflow

As mentioned earlier, at the moment the service can be consumed only through the API, so bulk of the time using our service will be spent dealing with the API in one way or another. Precisely, the whole process consists of composing the relevant data structures into a "problem" object and sending it to the server (the server uses the object to create the corresponding routing problem), making a request to the server with the object ID to queue the solution computation process, and retrieving the solution object from the server once the computation is done. These three steps are explained in more detail below:

The process starts with the construction of request object and making a POST request with the object to the server (/routing/request). The object's schema is outlined in the corresponding page in Routing API section. When the server receives the request, it creates a problem object using the data in the request body and responds back with the ID of the new object. Optionally, you can confirm that the server correctly created the object by making a GET request with the object's ID to /routing/request/{requestId}.
With the ID you received from the server in the first step, you can queue the computation by making a POST request to /routing/request/{requestId}/response. At first, the empty solution object is created at the server as a placeholder, and the server responds back with the ID of this object. The ID works as a handle to the solution object, because the object will be populated asynchronously after the computation process terminates. If for some reason you would like to cancel the current computation at any point before it finishes, you can send a PUT request to /routing/response/{responseId}/status to update the status. As this process can be quite long depending on the size of the problem, you can either periodically poll the server (GET request to /routing/response/{responseId}/status) for the computation status, or provide a callback URL when you make a request so that the server can notify the termination of the process. If the computation terminated unsuccessfully due to an error, it will respond with the reason for the failure.
When either the status of the computation changes to DONE or when you receive a callback, you can issue a GET request to /routing/response/{responseId} with the provided handle, and the server will respond with the associated solution object.

The Problem and Solution Object

Since the exact schema of these objects are explained in the API section, their schema won't be explained in full here. Briefly, the "problem" object consists of drivers, jobs, hard constraints, soft constraints and routing configuration. Routing configuration specifies which GIS to use for calculating time and distance, where the depot, if applicable, is located, and whether vehicles return to the depot when drivers finish their jobs. GIS should follow the structure:

{
  "type": "name of the GIS",
  "param1": "the value of the first parameter if it exists",
  "param2": ...,
  ...
}

Currently, there are 4 available GIS:

GIS name	Description	Parameters
EuclideanGIS	- The locations are points on Cartesian plane. - Euclidean distance is used for calculating distance between two points. - Time is simply distance / speed.
SimpleGIS	- Lat / Lng based GIS. - Distance between two points is approximated by calculating the straight distance and multiplying a constant that accounts for the difference. - Time is also distance / speed - Unit is m for distance, km/h for speed and s for time.	- drivingFactor (default = 1.26) - averageSpeed (default = 40)
PreciseGIS	Same as SimpleGIS, but distance is calculated using Haversine formula instead of naive Euclidean approximation.	- drivingFactor - averageSpeed
LongShortGIS	Also same as SimpleGIS, but there is a distance threshold that determines if it they are long or short, and two different drivingFactor/averageSpeed sets are used for calculating distance and time.	- shortDrivingFactor - shortAverageSpeed - longDrivingFactor - longAverageSpeed - distanceCriteria (default = 10000)

In addition to those attributes, route rule configuration can optionally be specified. The configuration object contains ruleCode and ruleWeight, where ruleCode is an ID of the mined rule returned from calling /mining endpoint, and ruleWeight determines how much the rule should be accounted for the solution. For further information about problem object, refer to the relevant pages in API section.

The "response" object consists of its ID, the ID of the problem object that corresponds to the solution, the status of the computation, the solution to the problem, timestamp and the configurations used for this computation. The most important of these is the solution object, as it contains the routing information. The object consists of the problem that the solution is for, and the set of computed routes. The routing plan, or ordered tasks assigned to a driver, is in the "tasks" object in each of the route. More details about the exact schema of these objects can be found at the "Data Schema" section and relevant pages in API documentation.