Make returning waypoints in API response optional with return_waypoints parameter

CHANGELOG.md

@@ -7,6 +7,7 @@
       - ADDED: direct mmapping of datafiles is now supported via the `--mmap` switch. [#5242](https://github.com/Project-OSRM/osrm-backend/pull/5242)
       - REMOVED: the previous `--memory_file` switch is now deprecated and will fallback to `--mmap` [#5242](https://github.com/Project-OSRM/osrm-backend/pull/5242)
       - ADDED: all waypoints in responses now contain a `distance` property between the original coordinate and the snapped location. [#5255](https://github.com/Project-OSRM/osrm-backend/pull/5255)
+      - ADDED: returning waypoints is now optional with the `return_waypoints` parameter [#5256](https://github.com/Project-OSRM/osrm-backend/pull/5256)
     - Windows:
       - FIXED: Windows builds again. [#5249](https://github.com/Project-OSRM/osrm-backend/pull/5249)
 

docs/http.md

@@ -29,6 +29,7 @@ To pass parameters to each location some options support an array like encoding:
 |bearings        |`{bearing};{bearing}[;{bearing} ...]`                   |Limits the search to segments with given bearing in degrees towards true north in clockwise direction. |
 |radiuses        |`{radius};{radius}[;{radius} ...]`                      |Limits the search to given radius in meters.                                                           |
 |generate\_hints |`true` (default), `false`                               |Adds a Hint to the response which can be used in subsequent requests, see `hints` parameter.           |
+|return\_waypoints|`true` (default), `false`                              |Returns information about the waypoints (snapped location, distance, name)                             |
 |hints           |`{hint};{hint}[;{hint} ...]`                            |Hint from previous request to derive position in street network.                                       |
 |approaches      |`{approach};{approach}[;{approach} ...]`                |Keep waypoints on curb side.                                                                           |
 |exclude         |`{class}[,{class}]`                                     |Additive list of classes to avoid, order does not matter.                                              |

docs/nodejs/api.md

@@ -58,6 +58,7 @@ Returns the fastest route between two or more coordinates while visiting the way
     -   `options.continue_straight` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** 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.
     -   `options.approaches` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Keep waypoints on curb side. Can be `null` (unrestricted, default) or `curb`.
                          `null`/`true`/`false`
+    -   `options.return_waypoints` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Return WayPoints in response (optional, default `true`)
 -   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)**
 
 **Examples**
@@ -90,6 +91,7 @@ Note: `coordinates` in the general options only supports a single `{longitude},{
     -   `options.number` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** Number of nearest segments that should be returned.
         Must be an integer greater than or equal to `1`. (optional, default `1`)
     -   `options.approaches` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Keep waypoints on curb side. Can be `null` (unrestricted, default) or `curb`.
+    -   `options.return_waypoints` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Return WayPoints in response (optional, default `true`)
 -   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)**
 
 **Examples**
@@ -131,6 +133,7 @@ tables. Optionally returns distance table.
     -   `options.approaches` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Keep waypoints on curb side. Can be `null` (unrestricted, default) or `curb`.
     -   `options.fallback_speed` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Replace `null` responses in result with as-the-crow-flies estimates based on `fallback_speed`.  Value is in metres/second.
     -   `options.fallback_coordinate` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** Either `input` (default) or `snapped`.  If using a `fallback_speed`, use either the user-supplied coordinate (`input`), or the snapped coordinate (`snapped`) for calculating the as-the-crow-flies diestance between two points.
+    -   `options.return_waypoints` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Return WayPoints in response (optional, default `true`)
 -   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)**
 
 **Examples**
@@ -272,6 +275,7 @@ Right now, the following combinations are possible:
     -   `options.source` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Return route starts at `any` or `first` coordinate. (optional, default `any`)
     -   `options.destination` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Return route ends at `any` or `last` coordinate. (optional, default `any`)
     -   `options.approaches` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)?** Keep waypoints on curb side. Can be `null` (unrestricted, default) or `curb`.
+    -   `options.return_waypoints` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Return WayPoints in response (optional, default `true`)
 -   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)**
 
 **Examples**

include/engine/api/base_parameters.hpp

@@ -72,6 +72,7 @@ struct BaseParameters
 
     // Adds hints to response which can be included in subsequent requests, see `hints` above.
     bool generate_hints = true;
+    bool return_waypoints = true;
 
     BaseParameters(const std::vector<util::Coordinate> coordinates_ = {},
                    const std::vector<boost::optional<Hint>> hints_ = {},
@@ -79,9 +80,11 @@ struct BaseParameters
                    std::vector<boost::optional<Bearing>> bearings_ = {},
                    std::vector<boost::optional<Approach>> approaches_ = {},
                    bool generate_hints_ = true,
-                   std::vector<std::string> exclude = {})
+                   std::vector<std::string> exclude = {},
+                   bool return_waypoints_ = true)
         : coordinates(coordinates_), hints(hints_), radiuses(radiuses_), bearings(bearings_),
-          approaches(approaches_), exclude(std::move(exclude)), generate_hints(generate_hints_)
+          approaches(approaches_), exclude(std::move(exclude)), generate_hints(generate_hints_),
+          return_waypoints(return_waypoints_)
     {
     }
 

include/engine/api/nearest_api.hpp

@@ -84,7 +84,10 @@ class NearestAPI final : public BaseAPI
             });
 
         response.values["code"] = "Ok";
-        response.values["waypoints"] = std::move(waypoints);
+        if (parameters.return_waypoints)
+        {
+            response.values["waypoints"] = std::move(waypoints);
+        }
     }
 
     const NearestParameters &parameters;

include/engine/api/route_api.hpp

@@ -62,8 +62,11 @@ class RouteAPI : public BaseAPI
                                                 route.target_traversed_in_reverse));
         }
 
-        response.values["waypoints"] =
-            BaseAPI::MakeWaypoints(raw_routes.routes[0].segment_end_coordinates);
+        if (parameters.return_waypoints)
+        {
+            response.values["waypoints"] =
+                BaseAPI::MakeWaypoints(raw_routes.routes[0].segment_end_coordinates);
+        }
         response.values["routes"] = std::move(jsRoutes);
         response.values["code"] = "Ok";
     }

include/engine/api/table_api.hpp

@@ -45,24 +45,27 @@ class TableAPI final : public BaseAPI
         auto number_of_destinations = parameters.destinations.size();
 
         // symmetric case
-        if (parameters.sources.empty())
+        if (parameters.return_waypoints)
         {
-            response.values["sources"] = MakeWaypoints(phantoms);
-            number_of_sources = phantoms.size();
-        }
-        else
-        {
-            response.values["sources"] = MakeWaypoints(phantoms, parameters.sources);
-        }
+            if (parameters.sources.empty())
+            {
+                response.values["sources"] = MakeWaypoints(phantoms);
+                number_of_sources = phantoms.size();
+            }
+            else
+            {
+                response.values["sources"] = MakeWaypoints(phantoms, parameters.sources);
+            }
 
-        if (parameters.destinations.empty())
-        {
-            response.values["destinations"] = MakeWaypoints(phantoms);
-            number_of_destinations = phantoms.size();
-        }
-        else
-        {
-            response.values["destinations"] = MakeWaypoints(phantoms, parameters.destinations);
+            if (parameters.destinations.empty())
+            {
+                response.values["destinations"] = MakeWaypoints(phantoms);
+                number_of_destinations = phantoms.size();
+            }
+            else
+            {
+                response.values["destinations"] = MakeWaypoints(phantoms, parameters.destinations);
+            }
         }
 
         if (parameters.annotations & TableParameters::AnnotationsType::Duration)

include/engine/api/trip_api.hpp

@@ -42,7 +42,10 @@ class TripAPI final : public RouteAPI
                                    sub_routes[index].target_traversed_in_reverse);
             routes.values.push_back(std::move(route));
         }
-        response.values["waypoints"] = MakeWaypoints(sub_trips, phantoms);
+        if (parameters.return_waypoints)
+        {
+            response.values["waypoints"] = MakeWaypoints(sub_trips, phantoms);
+        }
         response.values["trips"] = std::move(routes);
         response.values["code"] = "Ok";
     }

include/nodejs/node_osrm_support.hpp

@@ -659,6 +659,22 @@ inline bool argumentsToParameter(const Nan::FunctionCallbackInfo<v8::Value> &arg
         params->generate_hints = generate_hints->BooleanValue();
     }
 
+    if (obj->Has(Nan::New("return_waypoints").ToLocalChecked()))
+    {
+        v8::Local<v8::Value> return_waypoints =
+            obj->Get(Nan::New("return_waypoints").ToLocalChecked());
+        if (return_waypoints.IsEmpty())
+            return false;
+
+        if (!return_waypoints->IsBoolean())
+        {
+            Nan::ThrowError("return_waypoints must be of type Boolean");
+            return false;
+        }
+
+        params->return_waypoints = return_waypoints->BooleanValue();
+    }
+
     if (obj->Has(Nan::New("exclude").ToLocalChecked()))
     {
         v8::Local<v8::Value> exclude = obj->Get(Nan::New("exclude").ToLocalChecked());

include/server/api/base_parameters_grammar.hpp

@@ -152,6 +152,10 @@ struct BaseParametersGrammar : boost::spirit::qi::grammar<Iterator, Signature>
             qi::lit("generate_hints=") >
             qi::bool_[ph::bind(&engine::api::BaseParameters::generate_hints, qi::_r1) = qi::_1];
 
+        return_waypoints_rule =
+            qi::lit("return_waypoints=") >
+            qi::bool_[ph::bind(&engine::api::BaseParameters::return_waypoints, qi::_r1) = qi::_1];
+
         bearings_rule =
             qi::lit("bearings=") >
             (-(qi::short_ > ',' > qi::short_))[ph::bind(add_bearing, qi::_r1, qi::_1)] % ';';
@@ -166,11 +170,12 @@ struct BaseParametersGrammar : boost::spirit::qi::grammar<Iterator, Signature>
                        (qi::as_string[+qi::char_("a-zA-Z0-9")] %
                         ',')[ph::bind(&engine::api::BaseParameters::exclude, qi::_r1) = qi::_1];
 
-        base_rule = radiuses_rule(qi::_r1)         //
-                    | hints_rule(qi::_r1)          //
-                    | bearings_rule(qi::_r1)       //
-                    | generate_hints_rule(qi::_r1) //
-                    | approach_rule(qi::_r1)       //
+        base_rule = radiuses_rule(qi::_r1)           //
+                    | hints_rule(qi::_r1)            //
+                    | bearings_rule(qi::_r1)         //
+                    | generate_hints_rule(qi::_r1)   //
+                    | return_waypoints_rule(qi::_r1) //
+                    | approach_rule(qi::_r1)         //
                     | exclude_rule(qi::_r1);
     }
 
@@ -178,14 +183,13 @@ struct BaseParametersGrammar : boost::spirit::qi::grammar<Iterator, Signature>
     qi::rule<Iterator, Signature> base_rule;
     qi::rule<Iterator, Signature> query_rule;
 
-    qi::real_parser<double, json_policy> double_;
-
   private:
     qi::rule<Iterator, Signature> bearings_rule;
     qi::rule<Iterator, Signature> radiuses_rule;
     qi::rule<Iterator, Signature> hints_rule;
 
     qi::rule<Iterator, Signature> generate_hints_rule;
+    qi::rule<Iterator, Signature> return_waypoints_rule;
     qi::rule<Iterator, Signature> approach_rule;
     qi::rule<Iterator, Signature> exclude_rule;
 
@@ -197,6 +201,7 @@ struct BaseParametersGrammar : boost::spirit::qi::grammar<Iterator, Signature>
     qi::rule<Iterator, unsigned char()> base64_char;
     qi::rule<Iterator, std::string()> polyline_chars;
     qi::rule<Iterator, double()> unlimited_rule;
+    qi::real_parser<double, json_policy> double_;
 
     qi::symbols<char, engine::Approach> approach_type;
 };

test/nodejs/nearest.js

@@ -19,6 +19,18 @@ test('nearest', function(assert) {
     });
 });
 
+test('nearest', function(assert) {
+    assert.plan(2);
+    var osrm = new OSRM(data_path);
+    osrm.nearest({
+        coordinates: [three_test_coordinates[0]],
+        return_waypoints: false,
+    }, function(err, result) {
+        assert.ifError(err);
+        assert.equal(result.waypoints, undefined);
+    });
+});
+
 test('nearest', function(assert) {
     assert.plan(5);
     var osrm = new OSRM(data_path);

test/nodejs/route.js

@@ -19,6 +19,18 @@ test('route: routes Monaco', function(assert) {
     });
 });
 
+test('route: routes Monaco - no waypoints returned', function(assert) {
+    assert.plan(5);
+    var osrm = new OSRM(monaco_path);
+    osrm.route({coordinates: two_test_coordinates, return_waypoints: false}, function(err, route) {
+        assert.ifError(err);
+        assert.equal(route.waypoints, undefined);
+        assert.ok(route.routes);
+        assert.ok(route.routes.length);
+        assert.ok(route.routes[0].geometry);
+    });
+});
+
 test('route: routes Monaco on MLD', function(assert) {
     assert.plan(5);
     var osrm = new OSRM({path: monaco_mld_path, algorithm: 'MLD'});

test/nodejs/table.js

@@ -6,7 +6,7 @@ var three_test_coordinates = require('./constants').three_test_coordinates;
 var two_test_coordinates = require('./constants').two_test_coordinates;
 
 test('table: test annotations paramater combination', function(assert) {
-    assert.plan(12);
+    assert.plan(19);
     var osrm = new OSRM(data_path);
     var options = {
         coordinates: [three_test_coordinates[0], three_test_coordinates[1]],
@@ -45,7 +45,22 @@ test('table: test annotations paramater combination', function(assert) {
         assert.ifError(err);
         assert.ok(table['durations'], 'durations table result should exist');
         assert.notOk(table['distances'], 'distances table result should not exist');
+        assert.equal(table.sources.length, 2);
+        assert.equal(table.destinations.length, 2);
     });
+
+    options = {
+        coordinates: [three_test_coordinates[0], three_test_coordinates[1]],
+        return_waypoints: false
+    };
+    osrm.table(options, function(err, table) {
+        assert.ifError(err);
+        assert.ok(table['durations'], 'durations table result should exist');
+        assert.notOk(table['distances'], 'distances table result should not exist');
+        assert.equal(table.sources, undefined);
+        assert.equal(table.destinations, undefined);
+    });
+
 });
 
 test('table: returns buffer', function(assert) {

test/nodejs/trip.js

@@ -7,13 +7,26 @@ var two_test_coordinates = require('./constants').two_test_coordinates;
 
 
 test('trip: trip in Monaco', function(assert) {
-    assert.plan(2);
+    assert.plan(3);
     var osrm = new OSRM(data_path);
     osrm.trip({coordinates: two_test_coordinates}, function(err, trip) {
         assert.ifError(err);
         for (t = 0; t < trip.trips.length; t++) {
             assert.ok(trip.trips[t].geometry);
         }
+        assert.notEqual(trip.waypoints, undefined);
+    });
+});
+
+test('trip: trip in Monaco - no waypoints', function(assert) {
+    assert.plan(3);
+    var osrm = new OSRM(data_path);
+    osrm.trip({coordinates: two_test_coordinates, return_waypoints: false}, function(err, trip) {
+        assert.ifError(err);
+        for (t = 0; t < trip.trips.length; t++) {
+            assert.ok(trip.trips[t].geometry);
+        }
+        assert.equal(trip.waypoints, undefined);
     });
 });