Result Lists

Characteristic

Short description

The xRoute service provides various result lists such as legs, segments, nodes, the polylineA 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 routeA 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.

Visualization of how the result lists are composed from a route

Waypoints

We distinguish input waypoints and output waypoints. Result lists always link to the output waypointsA 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 the startNodeIndexand endNodeIndex to 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 which startSegmentIndex ≤ n ≤ endSegmentIndex.
Technical concept Route Locations, Waypoints and Route Legs
Technical concept Route Events