Skip to content

Route Model

Route Models

Overview

Route models are the data structures that map navigation systems use to represent the directions for a particular route. In the context of the DirectionService API, they are structurally represented as a series of Route, Leg, Step, and Edge business models, which typically include an origin, a destination, waypoints, a road network, and various properties such as length, duration, traffic, and warnings.

Route

The route model is the top-level object returned by the DirectionService API. A route is an overall path between two or more waypoints. It contains a series of Leg objects, each of which represents a portion of the journey between two waypoints. The route model contains metadata about the entire route, such as the total length, duration, and it also includes Travel Points along the route, including origin, intermediate stops, and final destination, which are used to calculate the estimated time of arrival(ETA).

Travel Point

A travel point is a location to which a user would like to travel through a route. This is a general concept applied to origin, waypoints, and final destination. It records the location information passed in, as well as the time zone and country code.

Here is an example to calculate the local ETA of the destination on a route. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// The followings are variables used in calculation, collected from different sources.
uint32_t duration = get the duration from origin to destination from route
tn::shared_ptr<TravelPoint> origin = get the origin from route
tn::shared_ptr<TravelPoint> dest = get the destination from route
double current_time = tn::simple_time::system_time();

// Convert the static time zone attributes to dynamic time zone info.
tn::foundation::TimeZoneInfo origin_timezone;
auto ec = tn::mapcontent::api::TimeUtility::getTimeZoneInfo(
            origin_timezone,
            origin->dst(),
            origin->utcOffset(),
            static_cast<uint32_t>(current_time),
            origin->countryCode());
if (tn::foundation::SDKError::OK != ec)
{
    // error handling
}
// Convert the dest_timezone in the same way.

// Calculate local time offset between destination and origin.
int32_t total_offset = dest_timezone.UTC_offset - origin_timezone.UTC_offset +
                       dest_timezone.DST_offset - origin_timezone.DST_offset;

// Get the local arrival time of destination.
// Note, this example assumes the local time of origin is the same as system local time.
// If it's not the truth, then you should use your own way to calculate local time.
double arrival_time = current_time + static_cast<double>(duration) + static_cast<double>(total_offset);
std::tm local_arrival_time = tn::simple_time::to_local_time(arrival_time);

Leg

A leg represents a portion of the journey between two waypoints, so a route will usually contain one fewer route leg than it has travel points. A leg may consist of one or more Steps depending on the actions the user needs to perform. The Leg model also contains metadata about the leg, such as the length, duration, as well as Characteristics and Major Road Names.

Characteristics

The characteristics are a series of notifications or warnings for the road's current leg that is passing through. This information could be shown to users, like "has tolls".

Major Road Names

The major road names are a list of names for the roads taking major portion of current leg. This information could be used to provide a general guideline to user, like "drives via US-101 N".

Here is an example of retrieving route characteristics and major road names:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// Get route response from the route calculation task
tn::shared_ptr<tn::direction::api::RouteResponse> route_response;

// Integrate guide for characteristics and major road names.
if (SDKError::OK == error_code)
{
    // Retrieve road notifications or warnings
    auto characteristics = route_response->routes().front()->legs().front()->characteristics();
    std::vector<std::string> warnings;
    for (const auto& characteristic : characteristics)
    {
        if (characteristic == tn::direction::models::v2::Characteristic::HasToll)
        {
            warnings.emplace_back("This route has tolls.");
        }
        else if (characteristic == tn::direction::models::v2::Characteristic::HasFerry)
        {
            warnings.emplace_back("This route includes a ferry.");
        }
    }

    // Retrieve major road names
    auto major_roads = route_response->routes().front()->legs().front()->majorRoads();
    std::string road_names;
    for (const auto& major_road : major_roads)
    {
        if (!road_names.empty())
        {
            road_names += " and ";
        }
        road_names += major_road;
    }
    std::string via_roads = "Via " + road_names;
}

Step

A step represents a section near the end of which the user needs to take action to follow the path. A step contains a maneuver, indicating the required action and corresponding details(such as Current/Next Road Names), and also one or more Edges, indicating detailed road segments. Please refer to another document that introduces guidance models for more details.

Current/Next Road Names

The current and next road names of turn-by-turn instructions are provided by steps as below. Note that this is a list of names with different usage types and formats. All the names belong to the same road, not multiple roads. If the current step really passes multiple roads, then the first one will be used.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// Get route response from the route calculation task
tn::shared_ptr<tn::direction::api::RouteResponse> route_response;

// Integrate guide for the current and next road names.
struct TurnName
{
    std::string current_road;
    std::string next_road;
};
std::vector<TurnName> turn_names;
if (SDKError::OK == error_code)
{
    auto steps = route_response->routes().front()->legs().front()->steps();
    for (std::size_t i = 0; i < steps.size(); ++i)
    {
        const auto& current_step = steps[i];

        TurnName turn_name;
        // Turn road name for the current step
        for (const auto& road_name : current_step->roadNames())
        {
            if (road_name.usage_type == tn::mapcontent::models::v1::NameString::UsageType::Official &&
                road_name.format == tn::mapcontent::models::v1::NameString::Format::Name)
            {
                turn_name.current_road = road_name.text;
            }
        }

        // Turn road name for the next step
        if (i < steps.size() - 1)
        {
            const auto& next_step = steps[i - 1];
            for (const auto& road_name : next_step->roadNames())
            {
                if (road_name.usage_type == tn::mapcontent::models::v1::NameString::UsageType::Official &&
                    road_name.format == tn::mapcontent::models::v1::NameString::Format::Name)
                {
                    turn_name.next_road = road_name.text;
                }
            }
        }
        turn_names.push_back(turn_name);
    }
}

Edge

An edge is the most basic element in a route and also in map data. It has a similar concept to the road segment defined in MapContent but only contains a subset of necessary information to save resources. It introduces metadata about length, road segment id, geometry, and traffic level, which can be used to draw the traffic condition on the route overview without spending time to query traffic from MapContent again.

Note that the value of traffic level is just a snapshot of the time when current route is calculated. If the latest traffic is needed, please query it again from MapContent.