Planning a Round Trip

This use case describes how to plan classical round trips starting at a depot and returning to it at the end of a tour.

All orders are delivered from one single depot, which is also the starting and ending point of the vehicle The term vehicle describes what is being routed or planned for. Vehicles are used in route calculation, distance matrix calculation and effectively also in tour planning. In route calculation, vehicle properties like overall size, weight and speed are in focus. In tour planning, it is vehicle properties like capacity and availability. Commonly a vehicle is motorized, like a truck - including its trailer or a car. However also a bike or even a pedestrian are included in this definition.'s journey. Sometimes, there are some return orders. To ensure efficient use of resources, the vehicles are expected to execute multiple deliveries from or to customers.

Example | The following picture shows an example of the desired tour structure

Geographical tour structure and stop sequence for round trips.

Benefits

Users learn how to parametrize the current use case.
Basic insight into how to influence the course of a tour.

Prerequisites

Please ensure following prerequisites are fulfilled before you start with the use case:

Installed and licensed PTV xTour service
License for as many vehicles as the plan should contain

Concepts

Programming Guide

This example explains how the request has to look like in order to influence the tour structure as mentioned in the use-case description above.

First we define our locations as OffRoadRouteLocations in the default EPSG:4326 format (see RequestBase.coordinateFormat). You could also use OnRoadRouteLocations, see the technical concept on waypoints and route legs for more information on the different types of route locations A route location is the position of an object to be routed to or from, which contains additional information on how to link this position to the road network and whether or or not this position is actually reached. Route locations are used as the input for route calculation and optimization throughout PTV xServer.. Since the use case describes deliveries from and to a single depot, we define one location as depot and the others as customer sites, see Orders, Locations, and Stops for more details. Most likely the locations have specific opening intervals, which may lead to multiple tours if two locations cannot be served by the same vehicle within their opening hours.

The fleet in this example consists of one type of vehicle, with two available vehicle instances (defined by the number of vehicle ids). Start and end location of these vehicles is the depot. To simplify the example code, we assume that the vehicles use direct distance (can be set in the distance mode of the request).

Since we do not want any other depots than the start and end depot to be involved in a tour and we do not want to return to the depot in between stops at customers, we need to activate the tour restrictions singleDepotPerTour and singleTripPerTour.

The last part of the example request are the orders, consisting of pickup and delivery orders that model the transportation of goods from the depot to a customer or from a customer to the depot. If no goods should be transported, please use visit orders instead.

We pass the request on to planTours. Once xTour has processed the request a callback is invoked which gives us access to the result of the calculation in form of a ToursResponse object.

The customer sites of the request are displayed in gray, the depot sites in orange. Since the ToursResponse only contains references to the given locations, the corresponding coordinates are taken from the request. The first tour of the result is displayed in gray, the second one in blue.