Return an array with meta-data for each coordinate.

Currently supports duration and distance for each coordinate.

This is particularly useful in map-matching, comparing how
a trip progresses compared to a real GPS trace that is
map-matched.

CHANGELOG.md

@@ -1,3 +1,10 @@
+# 5.2
+   Changes from 5.1
+
+   - API:
+     - new parameter `annotate` for `route` and `match` requests.  Returns additional data about each
+       coordinate along the selected/matched route line.
+
 # 5.1.0
    Changes with regard to 5.0.0
 

docs/http.md

@@ -145,6 +145,7 @@ In addition to the [general options](#general-options) the following options are
 |------------|------------------------------------------|-------------------------------------------------------------------------------|
 |alternatives|`true`, `false` (default)                 |Search for alternative routes and return as well.\*                            |
 |steps       |`true`, `false` (default)                 |Return route steps for each route leg                                          |
+|annotate    |`true`, `false` (default)                 |Returns additional metadata for each coordinate along the route geometry.      |
 |geometries  |`polyline` (default), `geojson`           |Returned route geometry format (influences overview and per step)             |
 |overview    |`simplified` (default), `full`, `false`   |Add overview geometry either full, simplified according to highest zoom level it could be display on, or not at all.|
 |continue_straight |`default` (default), `true`, `false`|Forces the route to keep going straight at waypoints and don't do a uturn even if it would be faster. Default value depends on the profile. |
@@ -247,6 +248,7 @@ In addition to the [general options](#general-options) the following options are
 |------------|------------------------------------------------|------------------------------------------------------------------------------------------|
 |steps       |`true`, `false` (default)                       |Return route steps for each route                                                         |
 |geometries  |`polyline` (default), `geojson`                 |Returned route geometry format (influences overview and per step)                        |
+|annotate    |`true`, `false` (default)                       |Returns additional metadata for each coordinate along the route geometry.                |
 |overview    |`simplified` (default), `full`, `false`         |Add overview geometry either full, simplified according to highest zoom level it could be display on, or not at all.|
 |timestamps  |`{timestamp};{timestamp}[;{timestamp} ...]`     |Timestamp of the input location.                                                          |
 |radiuses    |`{radius};{radius}[;{radius} ...]`              |Standard deviation of GPS precision used for map matching. If applicable use GPS accuracy.|
@@ -292,6 +294,7 @@ In addition to the [general options](#general-options) the following options are
 |Option      |Values                                          |Description                                                                |
 |------------|------------------------------------------------|---------------------------------------------------------------------------|
 |steps       |`true`, `false` (default)                       |Return route instructions for each trip                                    |
+|annotate    |`true`, `false` (default)                       |Returns additional metadata for each coordinate along the route geometry.      |
 |geometries  |`polyline` (default), `geojson`                 |Returned route geometry format (influences overview and per step)         |
 |overview    |`simplified` (default), `full`, `false`         |Add overview geometry either full, simplified according to highest zoom level it could be display on, or not at all.|
 
@@ -377,6 +380,13 @@ Represents a route between two waypoints.
    | true         | array of `RouteStep` objects describing the turn-by-turn instructions |
    | false        | empty array                                                           |
 
+- `annotation`: Additional details about each coordinate along the route geometry:
+
+   | annotate     |                                                                       |
+   |--------------|-----------------------------------------------------------------------|
+   | true         | returns distance and durations of each coordinate along the route     |
+   | false        | will not exist                                                        |
+
 #### Example
 
 With `steps=false`:

features/step_definitions/matching.js

@@ -33,7 +33,9 @@ module.exports = function () {
                     var subMatchings = [],
                         turns = '',
                         route = '',
-                        duration = '';
+                        duration = '',
+                        annotation = '';
+
 
                     if (res.statusCode === 200) {
                         if (headers.has('matchings')) {
@@ -54,6 +56,11 @@ module.exports = function () {
                             if (json.matchings.length != 1) throw new Error('*** Checking duration only supported for matchings with one subtrace');
                             duration = json.matchings[0].duration;
                         }
+
+                        if (headers.has('annotation')) {
+                            if (json.matchings.length != 1) throw new Error('*** Checking annotation only supported for matchings with one subtrace');
+                            annotation = this.annotationList(json.matchings[0]);
+                        }
                     }
 
                     if (headers.has('turns')) {
@@ -68,6 +75,10 @@ module.exports = function () {
                         got.duration = duration.toString();
                     }
 
+                    if (headers.has('annotation')) {
+                        got.annotation = annotation.toString();
+                    }
+
                     var ok = true;
                     var encodedResult = '',
                         extendedTarget = '';
@@ -134,6 +145,7 @@ module.exports = function () {
                     this.requestUrl(row.request, afterRequest);
                 } else {
                     var params = this.queryParams;
+                    params['annotate'] = 'true';
                     got = {};
                     for (var k in row) {
                         var match = k.match(/param:(.*)/);

features/support/route.js

@@ -141,6 +141,16 @@ module.exports = function () {
         return this.extractInstructionList(instructions, s => s.maneuver.bearing_after);
     };
 
+    this.annotationList = (instructions) => {
+        // Pull out all the distinct segment distances, skipping the arrive
+        // instructions, and the leading 0 on all timestamps arrays.
+        var pairs = [];
+        for (var i in instructions.annotation.duration) {
+            pairs.push(instructions.annotation.duration[i]+":"+instructions.annotation.distance[i]);
+        }
+        return pairs.join(",");
+    };
+
     this.turnList = (instructions) => {
         return instructions.legs.reduce((m, v) => m.concat(v.steps), [])
             .map(v => {

features/testbot/matching.feature

@@ -104,3 +104,18 @@ Feature: Basic Map Matching
             | trace | matchings |
             | dcba  | hg,gf,fe  |
             | efgh  | ab,bc,cd  |
+
+    Scenario: Testbot - Duration details
+        Given the node map
+            | a | b | c | d | e |   | g | h |
+            |   |   | i |   |   |   |   |   |
+
+        And the ways
+            | nodes    | oneway |
+            | abcdegh  | no     |
+            | ci       | no     |
+
+        When I match I should get
+            | trace | matchings | annotation                                                                     |
+            | abeh  | abcedgh   | 1:9.897633,0:0,1:10.008842,1:10.008842,1:10.008842,0:0,2:20.017685,1:10.008842 |
+            | abci  | abc,ci    | 1:9.897633,0:0,1:10.008842,0:0.111209,1:10.121593                              |

include/engine/api/match_parameters.hpp

@@ -52,6 +52,7 @@ struct MatchParameters : public RouteParameters
 {
     MatchParameters()
         : RouteParameters(false,
+                          false,
                           false,
                           RouteParameters::GeometriesType::Polyline,
                           RouteParameters::OverviewType::Simplified,

include/engine/api/route_api.hpp

@@ -176,9 +176,33 @@ class RouteAPI : public BaseAPI
                 });
         }
 
-        return json::makeRoute(route,
+        auto result = json::makeRoute(route,
                                json::makeRouteLegs(std::move(legs), std::move(step_geometries)),
                                std::move(json_overview));
+
+        if (parameters.annotation)
+        {
+            util::json::Array durations;
+            util::json::Array distances;
+            for (const auto idx : util::irange<std::size_t>(0UL, leg_geometries.size()))
+            {
+                auto &leg_geometry = leg_geometries[idx];
+                std::for_each(leg_geometry.annotations.begin(),
+                              leg_geometry.annotations.end(),
+                              [this, &durations, &distances](const guidance::LegGeometry::Annotation &step) {
+                                  durations.values.push_back(step.duration);
+                                  distances.values.push_back(step.distance);
+                              });
+            }
+
+            util::json::Object details;
+            details.values["distance"] = std::move(distances);
+            details.values["duration"] = std::move(durations);
+
+            result.values["annotation"] = std::move(details);
+        }
+
+        return result;
     }
 
     const RouteParameters &parameters;

include/engine/api/route_parameters.hpp

@@ -72,17 +72,20 @@ struct RouteParameters : public BaseParameters
     template <typename... Args>
     RouteParameters(const bool steps_,
                     const bool alternatives_,
+                    const bool annotation_,
                     const GeometriesType geometries_,
                     const OverviewType overview_,
                     const boost::optional<bool> continue_straight_,
                     Args... args_)
         : BaseParameters{std::forward<Args>(args_)...}, steps{steps_}, alternatives{alternatives_},
-          geometries{geometries_}, overview{overview_}, continue_straight{continue_straight_}
+          annotation{annotation_}, geometries{geometries_}, overview{overview_},
+          continue_straight{continue_straight_}
     {
     }
 
     bool steps = false;
     bool alternatives = false;
+    bool annotation = false;
     GeometriesType geometries = GeometriesType::Polyline;
     OverviewType overview = OverviewType::Simplified;
     boost::optional<bool> continue_straight;

include/engine/guidance/assemble_geometry.hpp

@@ -43,34 +43,40 @@ LegGeometry assembleGeometry(const DataFacadeT &facade,
     geometry.segment_offsets.push_back(0);
     geometry.locations.push_back(source_node.location);
 
+    auto cumulative_distance = 0.;
     auto current_distance = 0.;
     auto prev_coordinate = geometry.locations.front();
     for (const auto &path_point : leg_data)
     {
         auto coordinate = facade.GetCoordinateOfNode(path_point.turn_via_node);
-        current_distance +=
+        current_distance =
             util::coordinate_calculation::haversineDistance(prev_coordinate, coordinate);
+        cumulative_distance += current_distance;
 
         // all changes to this check have to be matched with assemble_steps
         if (path_point.turn_instruction.type != extractor::guidance::TurnType::NoTurn)
         {
-            geometry.segment_distances.push_back(current_distance);
+            geometry.segment_distances.push_back(cumulative_distance);
             geometry.segment_offsets.push_back(geometry.locations.size());
-            current_distance = 0.;
+            cumulative_distance = 0.;
         }
 
         prev_coordinate = coordinate;
+        geometry.annotations.emplace_back(LegGeometry::Annotation{current_distance, path_point.duration_until_turn / 10.});
         geometry.locations.push_back(std::move(coordinate));
     }
-    current_distance +=
+    current_distance =
         util::coordinate_calculation::haversineDistance(prev_coordinate, target_node.location);
+    cumulative_distance += current_distance;
     // segment leading to the target node
-    geometry.segment_distances.push_back(current_distance);
+    geometry.segment_distances.push_back(cumulative_distance);
+    geometry.annotations.emplace_back(LegGeometry::Annotation{current_distance, target_node.forward_weight / 10.});
     geometry.segment_offsets.push_back(geometry.locations.size());
     geometry.locations.push_back(target_node.location);
 
     BOOST_ASSERT(geometry.segment_distances.size() == geometry.segment_offsets.size() - 1);
     BOOST_ASSERT(geometry.locations.size() > geometry.segment_distances.size());
+    BOOST_ASSERT(geometry.annotations.size() == geometry.locations.size() - 1);
 
     return geometry;
 }

include/engine/guidance/leg_geometry.hpp

@@ -31,6 +31,13 @@ struct LegGeometry
     // length of the segment in meters
     std::vector<double> segment_distances;
 
+    // Per-coordinate metadata
+    struct Annotation {
+        double distance;
+        double duration;
+    };
+    std::vector<Annotation> annotations;
+
     std::size_t FrontIndex(std::size_t segment_index) const
     {
         return segment_offsets[segment_index];

include/server/api/route_parameters_grammar.hpp

@@ -57,6 +57,7 @@ struct RouteParametersGrammar : public BaseParametersGrammar<Iterator, Signature
         base_rule =
             BaseGrammar::base_rule(qi::_r1)
             | (qi::lit("steps=") > qi::bool_[ph::bind(&engine::api::RouteParameters::steps, qi::_r1) = qi::_1])
+            | (qi::lit("annotate=") > qi::bool_[ph::bind(&engine::api::RouteParameters::annotation, qi::_r1) = qi::_1])
             | (qi::lit("geometries=") > geometries_type[ph::bind(&engine::api::RouteParameters::geometries, qi::_r1) = qi::_1])
             | (qi::lit("overview=") > overview_type[ph::bind(&engine::api::RouteParameters::overview, qi::_r1) = qi::_1])
             ;

src/engine/guidance/post_processing.cpp

@@ -626,6 +626,7 @@ void trimShortSegments(std::vector<RouteStep> &steps, LegGeometry &geometry)
     {
         // fixup the coordinate
         geometry.locations.erase(geometry.locations.begin());
+        geometry.annotations.erase(geometry.annotations.begin());
 
         // remove the initial distance value
         geometry.segment_distances.erase(geometry.segment_distances.begin());
@@ -687,6 +688,7 @@ void trimShortSegments(std::vector<RouteStep> &steps, LegGeometry &geometry)
     if (next_to_last_step.distance <= 1)
     {
         geometry.locations.pop_back();
+        geometry.annotations.pop_back();
         geometry.segment_offsets.pop_back();
         BOOST_ASSERT(geometry.segment_distances.back() < 1);
         geometry.segment_distances.pop_back();
@@ -713,6 +715,7 @@ void trimShortSegments(std::vector<RouteStep> &steps, LegGeometry &geometry)
         // correct steps but duplicated coordinate in the end.
         // This can happen if the last coordinate snaps to a node in the unpacked geometry
         geometry.locations.pop_back();
+        geometry.annotations.pop_back();
         geometry.segment_offsets.back()--;
         // since the last geometry includes the location of arrival, the arrival instruction
         // geometry overlaps with the previous segment

unit_tests/server/parameters_parser.cpp

@@ -85,6 +85,7 @@ BOOST_AUTO_TEST_CASE(valid_route_urls)
     BOOST_CHECK_EQUAL(reference_1.steps, result_1->steps);
     BOOST_CHECK_EQUAL(reference_1.alternatives, result_1->alternatives);
     BOOST_CHECK_EQUAL(reference_1.geometries, result_1->geometries);
+    BOOST_CHECK_EQUAL(reference_1.annotation, result_1->annotation);
     BOOST_CHECK_EQUAL(reference_1.overview, result_1->overview);
     BOOST_CHECK_EQUAL(reference_1.continue_straight, result_1->continue_straight);
     CHECK_EQUAL_RANGE(reference_1.bearings, result_1->bearings);
@@ -95,13 +96,15 @@ BOOST_AUTO_TEST_CASE(valid_route_urls)
     RouteParameters reference_2{};
     reference_2.alternatives = true;
     reference_2.steps = true;
+    reference_2.annotation = true;
     reference_2.coordinates = coords_1;
     auto result_2 = parseParameters<RouteParameters>(
-        "1,2;3,4?steps=true&alternatives=true&geometries=polyline&overview=simplified");
+        "1,2;3,4?steps=true&alternatives=true&geometries=polyline&overview=simplified&annotate=true");
     BOOST_CHECK(result_2);
     BOOST_CHECK_EQUAL(reference_2.steps, result_2->steps);
     BOOST_CHECK_EQUAL(reference_2.alternatives, result_2->alternatives);
     BOOST_CHECK_EQUAL(reference_2.geometries, result_2->geometries);
+    BOOST_CHECK_EQUAL(reference_2.annotation, result_2->annotation);
     BOOST_CHECK_EQUAL(reference_2.overview, result_2->overview);
     BOOST_CHECK_EQUAL(reference_2.continue_straight, result_2->continue_straight);
     CHECK_EQUAL_RANGE(reference_2.bearings, result_2->bearings);
@@ -109,7 +112,7 @@ BOOST_AUTO_TEST_CASE(valid_route_urls)
     CHECK_EQUAL_RANGE(reference_2.coordinates, result_2->coordinates);
     CHECK_EQUAL_RANGE(reference_2.hints, result_2->hints);
 
-    RouteParameters reference_3{false, false, RouteParameters::GeometriesType::GeoJSON,
+    RouteParameters reference_3{false, false, false, RouteParameters::GeometriesType::GeoJSON,
                                 RouteParameters::OverviewType::False, true};
     reference_3.coordinates = coords_1;
     auto result_3 = api::parseParameters<engine::api::RouteParameters>(
@@ -119,6 +122,7 @@ BOOST_AUTO_TEST_CASE(valid_route_urls)
     BOOST_CHECK_EQUAL(reference_3.steps, result_3->steps);
     BOOST_CHECK_EQUAL(reference_3.alternatives, result_3->alternatives);
     BOOST_CHECK_EQUAL(reference_3.geometries, result_3->geometries);
+    BOOST_CHECK_EQUAL(reference_3.annotation, result_3->annotation);
     BOOST_CHECK_EQUAL(reference_3.overview, result_3->overview);
     BOOST_CHECK_EQUAL(reference_3.continue_straight, result_3->continue_straight);
     CHECK_EQUAL_RANGE(reference_3.bearings, result_3->bearings);
@@ -137,6 +141,7 @@ BOOST_AUTO_TEST_CASE(valid_route_urls)
                                  "39KAAAAHgAAACEAAAAAAAAAGAAAAE0BAABOAQAAGwAAAIAzcQBkUJsC1zNxAHBQmw"
                                  "IAAAEBl-Umfg==")};
     RouteParameters reference_4{false,
+                                false,
                                 false,
                                 RouteParameters::GeometriesType::Polyline,
                                 RouteParameters::OverviewType::Simplified,
@@ -154,6 +159,7 @@ BOOST_AUTO_TEST_CASE(valid_route_urls)
     BOOST_CHECK_EQUAL(reference_4.steps, result_4->steps);
     BOOST_CHECK_EQUAL(reference_4.alternatives, result_4->alternatives);
     BOOST_CHECK_EQUAL(reference_4.geometries, result_4->geometries);
+    BOOST_CHECK_EQUAL(reference_4.annotation, result_4->annotation);
     BOOST_CHECK_EQUAL(reference_4.overview, result_4->overview);
     BOOST_CHECK_EQUAL(reference_4.continue_straight, result_4->continue_straight);
     CHECK_EQUAL_RANGE(reference_4.bearings, result_4->bearings);
@@ -165,6 +171,7 @@ BOOST_AUTO_TEST_CASE(valid_route_urls)
         boost::none, engine::Bearing{200, 10}, engine::Bearing{100, 5},
     };
     RouteParameters reference_5{false,
+                                false,
                                 false,
                                 RouteParameters::GeometriesType::Polyline,
                                 RouteParameters::OverviewType::Simplified,
@@ -178,6 +185,7 @@ BOOST_AUTO_TEST_CASE(valid_route_urls)
     BOOST_CHECK_EQUAL(reference_5.steps, result_5->steps);
     BOOST_CHECK_EQUAL(reference_5.alternatives, result_5->alternatives);
     BOOST_CHECK_EQUAL(reference_5.geometries, result_5->geometries);
+    BOOST_CHECK_EQUAL(reference_5.annotation, result_5->annotation);
     BOOST_CHECK_EQUAL(reference_5.overview, result_5->overview);
     BOOST_CHECK_EQUAL(reference_5.continue_straight, result_5->continue_straight);
     CHECK_EQUAL_RANGE(reference_5.bearings, result_5->bearings);
@@ -196,6 +204,7 @@ BOOST_AUTO_TEST_CASE(valid_route_urls)
     BOOST_CHECK_EQUAL(reference_6.steps, result_6->steps);
     BOOST_CHECK_EQUAL(reference_6.alternatives, result_6->alternatives);
     BOOST_CHECK_EQUAL(reference_6.geometries, result_6->geometries);
+    BOOST_CHECK_EQUAL(reference_6.annotation, result_6->annotation);
     BOOST_CHECK_EQUAL(reference_6.overview, result_6->overview);
     BOOST_CHECK_EQUAL(reference_6.continue_straight, result_6->continue_straight);
     CHECK_EQUAL_RANGE(reference_6.bearings, result_6->bearings);
@@ -211,6 +220,7 @@ BOOST_AUTO_TEST_CASE(valid_route_urls)
     BOOST_CHECK_EQUAL(reference_7.steps, result_7->steps);
     BOOST_CHECK_EQUAL(reference_7.alternatives, result_7->alternatives);
     BOOST_CHECK_EQUAL(reference_7.geometries, result_7->geometries);
+    BOOST_CHECK_EQUAL(reference_7.annotation, result_7->annotation);
     BOOST_CHECK_EQUAL(reference_7.overview, result_7->overview);
     BOOST_CHECK_EQUAL(reference_7.continue_straight, result_7->continue_straight);
     CHECK_EQUAL_RANGE(reference_7.bearings, result_7->bearings);
@@ -247,6 +257,7 @@ BOOST_AUTO_TEST_CASE(valid_route_urls)
                                  "IFAAEBl-Umfg=="),
         boost::none};
     RouteParameters reference_10{false,
+                                false,
                                 false,
                                 RouteParameters::GeometriesType::Polyline,
                                 RouteParameters::OverviewType::Simplified,
@@ -263,6 +274,7 @@ BOOST_AUTO_TEST_CASE(valid_route_urls)
     BOOST_CHECK_EQUAL(reference_10.steps, result_10->steps);
     BOOST_CHECK_EQUAL(reference_10.alternatives, result_10->alternatives);
     BOOST_CHECK_EQUAL(reference_10.geometries, result_10->geometries);
+    BOOST_CHECK_EQUAL(reference_10.annotation, result_10->annotation);
     BOOST_CHECK_EQUAL(reference_10.overview, result_10->overview);
     BOOST_CHECK_EQUAL(reference_10.continue_straight, result_10->continue_straight);
     CHECK_EQUAL_RANGE(reference_10.bearings, result_10->bearings);