Route Locations, Waypoints and Route Legs


Short description | Route Locations

Short description | Waypoints

Hover for glossary definition: waypointA 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

Detailed Consideration


Things to consider
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.


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.


Visualisation of an 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.


Visualisation of an OnRoadWaypoint

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


Visualisation of a 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.


Visualisation of a CombinedTransportWaypoint

The route takes the specified combined transportThe 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 profileA 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.

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