Route Locations, Waypoints and Route Legs

This Technical Concept is relevant to the following Services: xRoute, xDima, xTour, xCluster.

Characteristic

Short description | Route Locations

Hover for glossary definition: route location

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.

For all services based on route

A route corresponds to a path of a vehicle through the underlying transport network. The main attributes of a route are the distance and the time that the vehicle travels along the path. calculation each location is represented by a RouteLocation.
The user can decide for each location how to be treated during route calculation. PTV xServer supports two types of route locations which basically control whether or not the location is part of the route:

OffRoadRouteLocation
OnRoadRouteLocation

Short description | Waypoints

Hover for glossary definition: waypoint

A waypoint is a geographic location used to specify start, destination and possible stopovers for a route.

From the PTV xRoute point we distinguish

Input Waypoints
Output Waypoints

Short description | Route Legs

Hover for glossary definition: route leg

A route leg is a part of a route between two consecutive waypoints.

Detailed Consideration

OffRoadRouteLocation

Things to consider	The location is usually off the road. The location is actually reached, i.e. 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. stops at this location. Furthermore, the vehicle or the driver leaves the road. The route starts or ends at the location. The polyline A polyline is a continuous line composed of one or more line segments given as a set of tuples with x,y and optional z coordinates. contains a straight line from the nearest road to the location. The distance and travel time from this route location to the next route location contains the length of this straight line and the assumed travel time for that. An optional second geographical location can be specified, the `roadAccessCoordinate`. This is useful if the `offRoadCoordinate` has to be accessed from the road network not by the geographically nearest road. In such cases the`roadAccessCoordinate` helps because then the geographically nearest road to this coordinate is used to access the `offRoadCoordinate`. The PTV xLocate service can often provide a `roadAccessCoordinate` for a Location, as it is shown in the Route Geocoded Addresses Sample. A sample route that shows the importance of the `roadAccessCoordinate` is from Rue Ermesinde 36, 1469 Lëtzebuerg to Rue Ermesinde 50, 1469 Lëtzebuerg. An optional flag sideOfStreetRestriction can be set to SAME_SIDE_AS_LOCATION. This is useful to force the route to start and arrive at the side of the road on which the location is located.
Typical use cases	Calculating a route for a postman who has to deliver the letters to the post boxes at the houses. The distance from the road network to the house has to be considered for the total route distance. Calculate a route from house entrance to house entrance. Calculate a route from or to a location that is off the road, i.e. on a construction site, an industrial area, or similar.
Use it if	The location represents a specific building. Locations like this can be retrieved through the PTV xLocate service which provides `referenceCoordinate` and `roadAccessCoordinate` for addresses with house number for many countries. The location represents a ramp or a platform for a truck, a position of an engine or a device to be delivered to or from a construction site, or similar. The location is retrieved through a click into a detailed map which is supposed to represent a building. It is forbidden for the vehicle to cross the road, when starting or arriving at this location. Set sideOfStreetRestriction to SAME_SIDE_AS_LOCATION in this usecase.

OnRoadRouteLocation

Things to consider	The location can be on or off the road, it usually does not matter. The location is not actually reached, i.e. the vehicle stops at the road or passes by. The route starts or ends on the road network. If the given location is off the road it is not directly reached by the route. The polyline starts or ends on the road network. If the given location is off the road it is not contained in the polyline. The distance and travel time from this route location to the next route location does not contain the distance from the input location to the route network nor the assumed travel time for that. An optional flag considerAlternativeNearByRoads can be set to true. This is useful if the location is not precise and also nearby roads should be considered as potential start or end points of the route. An optional flag sideOfStreetRestriction can be set to SAME_SIDE_AS_LOCATION. This is useful to force the route to start and arrive at the side of the road on which the location is located.
Typical use cases	Delivery vehicle stops on the road. The total route distance shall cover only the driven distance on the road network. Calculating a route where only the road distance matters. Calculating a route from city to city.
Use it if	The location represents something else but a building such as the reference coordinate of a street or a city. For addresses without a house number the PTV xLocate service provides only this reference coodinate. A click into a map usually yields a position which does not represent a building. The location represents a crossing or an interchange. Set considerAlternativeNearByRoads to true to avoid using a wrong ramp. The location is retrieved from a GPS device in a vehicle. Set considerAlternativeNearByRoads to true to avoid using the wrong lane. The location is retrieved from some other source and does not represent a building.

Input Waypoints

The PTV xRoute service has several input waypoints, see the entities that extend InputWaypoint. In particular, there is one input waypoint for each of the above described route locations, the OffRoadWaypoint and the OnRoadWaypoint - try the different behavior in the showcase Apply Different Waypoint Types.

Normally one input waypoint corresponds to one output waypoint in the response, see also the next section. There are three exceptions: on the one hand, a PathWaypoint generates multiple output waypoints, see also the technical concept on encoded path. On the other hand, a ManipulateRouteWaypoint and CombinedTransportViaWaypoint do not appear as output waypoints at all.

OffRoadWaypoint

The distance and traveltime from this waypoint to the road network is estimated and included in the response. For each OffRoadWaypoints, there is a corresponding waypoint in the response.

OnRoadWaypoint

Each OnRoadWaypoint add a corresponding waypoint in the response. Each corresponding OnRoadWaypoint is directly placed on the road network.

ManipulateRouteWaypoint

The route passes near the specified waypoint coordinate specified in the manipulateRouteWaypoint. A manipulateRouteWaypoint does not add a corresponding waypoint in the response. Moreover, it can't be neither the start or the end of a route, only a via waypoint.

CombinedTransportWaypoint

The route takes the specified combined transport The combined transport is a form of transport where the vehicle in question does not drive itself but is transported by a boat or by rail (piggyback). id. A combinedTransportWaypoint does not add a corresponding waypoint in the response. Moreover, it can't be neither the start or the end of a route, only a via waypoint.

Output Waypoints

The PTV xRoute service returns waypoints upon request. Such returned waypoints are called output waypoints. As mentioned in the previous section it is not guaranteed that there is an output waypoint for each input waypoint. The mapping from input to output waypoints can be done by a user defined ID. If such an ID is set at the input waypoint the corrsponding output waypoint contains this ID as a field.

Each output waypoint is of the type Waypoint which contains several calculated properties. These calculated properties are the distance from the user-defined input location to the geographically nearest point on the road network which is called the linkedCoordinate. The field linkTravelTime refers to the linkDistance divided by the field speedForLinkDistance defined in the vehicle profile A profile is a collection of parameters used to configure the request. Full profiles consist of a number of specialized sub-profiles like the VehicleProfile which describes the properties of a vehicle.. Note that for waypoints that correspond to an OnRoadWaypoint in the request the linkTravelTime is always 0 because the linkDistance is not part of the route in this case. To mark the output waypoint on a map, the referenceCoordinate can be used, as it is always part of the route.

Via Waypoints

In addition to the OffRoadWaypoint and OnRoadWaypoint described above, the PTV xRoute service offers other InputWaypoint types that can be used as Via waypoints to influence the route calculation according to some user preferences.

ManipulateRouteWaypoint : This InputWaypoint type is used to attract the route around a certain coordinate within a user defined radius. this is particularly useful to prefer passing through a specified area instead of the default one.
CombinedTransportViaWaypoint : This InputWaypoint type is used to force the route passage through the specified combined transport. For example, it can be used to prefer one ferry crossing over another.

Changing vehicle parameters at waypoint

For OffRoadWaypoint, OnRoadWaypoint and MultiCoordinateOnRoadWaypoint, it is possible to change some vehicle parameters. This feature could be useful to get the best route which fits the current parameters of the vehicle. For example, the real weight, the number of trailers,...
For each waypoint, it is possible to change any of the VehicleParametersAtWaypoint. Please note that the changes are applied for all the next waypoints until there is another change or until the end of the route.

Be aware that, using this feature will have an impact on the performance.

Route Legs

A Route Leg can be identified by the IDs of its constitutive waypoints. It contains data like the travel time and distance needed for the leg, its polyline, and indices pointing to the segment and nodes lists.

Good to know

Empty Routes and Route Legs

A route or route leg which connects two route locations that are identical is called empty. The PTV xRoute service will return 0 as the travel time and 0 as the distance. Per definition it will contain one segment of distance and travel time 0. The segment of an empty route has the type NOT_DRIVING.

A special case of an empty route leg is one that connects two different OnRoadRouteLocations which are linked exactly to the same point on the road network.

In all other cases when route legs between two different route locations are calculated the route leg consists of at least one "real" segment. Note, however, that also such a route leg may have a travel time or distance of 0 if the route locations are very close to each other.

Showcase	Apply different waypoint types
Integration Sample	Calculating a route
Technical concept	Encoded Path