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 theroadAccessCoordinate 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.
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
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.
OnRoadWaypoint
Visualisation of an OnRoadWaypoint
Each OnRoadWaypoint add a corresponding waypoint in the response. Each corresponding OnRoadWaypoint is directly placed on the road network.
ManipulateRouteWaypoint
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.
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.
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.
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.