Characteristic
Short description
The xRoute service provides various result lists such as legs, segments, nodes, 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., or 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. events which are linked to each other. These links are automatically returned using the zero-based index of the corresponding result list. Their purpose is to obtain related information but to avoid duplication in the response.
Use
A special request flag is not necessary.
Detailed Consideration
Main Result Lists
The main result of a route calculation, the route itself, consists of a hierarchy of objects. Each level of this hierarchy increases in detail and decreases in geographical extent.
- A route consists of at least one leg.
- Every Leg is linked to its start and end segment (which may be the same for an empty leg) and to its start and end node.
- Every Segment is linked to its start and end node.
- Every Node is linked to the corresponding point of the polyline.
Waypoints
We distinguish input waypoints and output waypoints. Result lists always link to the output waypoints A waypoint is a geographic location used to specify start, destination and possible stopovers for a route. by index but to the input waypoints by name. In order to identify an input waypoint, provide a unique name.
This is due to the fact that the input waypoint list and the output waypoint list do not necessary have the same size and objects with the same index do not necessarily link to related objects. For example, a PathWaypoint connects two output waypoints whereas a ManipulateRouteWaypoint is never actually reached and thus not present in the output waypoint list.
A leg always connects two output waypoints, therefore it is not linked to the output waypoint list. The leg at index n connects the output waypoints at index n and n+1. Additionally, it contains the names of the input waypoints it connects, if present. For a PathWaypoint the names are equal.
Route Events
The RouteEvent base type links only to the node list, but following the guarantees below, this index is also valid for the segment list except for the very last node. Other subclasses such as the WaypointEvent contain further indices to other result lists.
Good to know
Availability
An index field always has the suffix Index. It is present in the response, if the corresponding result list is requested. Otherwise the index field is not present.
Please note that a result list is also omitted if it is empty.
Guarantees
There are some conditions which always hold.
- Every route and every leg always consists of at least one segment, even if start and destination are equal.
- The number of nodes of a route or leg always equals the number of segments plus 1.
- Consequently, the index of a segment is always equal to the index of the start node of the segment.
- A segment always connects two consecutive nodes. Therefore,
endNodeIndex = startNodeIndex + 1. - The leg at index n connects the output waypoints at index n and n+1.
Use Cases
The following examples illustrate what related data can be retrieved using the indexes to other result lists.
- I want to mark the start and end of a segment on the map, but the Segment type does not contain the coordinates.
→ Follow thestartNodeIndexandendNodeIndexto obtain the corresponding Node types which contain the coordinates. - I want to know to which leg my segment at index n belongs.
→ Iterate the legs and search for that leg for whichstartSegmentIndex ≤ n ≤ endSegmentIndex.
Related Topics
| Technical concept | Route Locations, Waypoints and Route Legs |
| Technical concept | Route Events |