Skip to content

Deprecate and remove hints parameter: silently ignore input, remove hint generation from responses #7387

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Copilot wants to merge 11 commits into from
Closed

Deprecate and remove hints parameter: silently ignore input, remove hint generation from responses #7387

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
aeddb4d
Initial plan
Copilot Mar 1, 2026
f411146
Deprecate hints parameter: silently ignore from HTTP, remove usage fr…
Copilot Mar 1, 2026
c544ade
Ensure hints are silently ignored at earliest convenience: Node.js bi…
Copilot Mar 1, 2026
89d286a
Fix clang-format violation in base_parameters_grammar.hpp (#7389)
Copilot Mar 1, 2026
2fa0560
Regenerate docs/nodejs/api.md to reflect options.hints deprecation (#…
Copilot Mar 1, 2026
7494d70
Remove hint generation: drop generate_hints parameter and hint field …
Copilot Mar 1, 2026
3849565
Merge branch 'master' into copilot/deprecate-hints-parameter
DennisOSRM Mar 3, 2026
5e607dc
Fix clang-format-18 formatting violations in deprecate-hints PR (#7395)
Copilot Mar 3, 2026
b0c7a72
Fix compile error in route.cpp caused by clang-format mangling initia…
DennisOSRM Mar 3, 2026
e476c54
Fix unit test compilation
DennisOSRM Mar 3, 2026
7ac10a0
Keep hint field as empty string for backward compatibility; fix clang…
DennisOSRM Mar 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions docs/http.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ 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 a 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. |
|hints |`{hint};{hint}[;{hint} ...]` |Hint from previous request to derive position in street network. |
|generate\_hints |`true`, `false` |**Deprecated**. This parameter is silently ignored. |
|hints |`{hint};{hint}[;{hint} ...]` |**Deprecated**. This parameter is silently ignored. |
|approaches |`{approach};{approach}[;{approach} ...]` |Restrict the direction on the road network at a waypoint, relative to the input coordinate. |
|exclude |`{class}[,{class}]` |Additive list of classes to avoid, the order does not matter. |
|snapping |`default` (default), `any` |Default snapping avoids is_startpoint (see profile) edges, `any` will snap to any edge in the graph |
Expand All @@ -46,7 +46,6 @@ Where the elements follow the following format:
|------------|--------------------------------------------------------|
|bearing |`{value},{range}` `integer 0 .. 360,integer 0 .. 180` |
|radius |`double >= 0` or `unlimited` (default) |
|hint |Base64 `string` |
|approach |`curb`, `opposite` or `unrestricted` (default) |
|class |A class name determined by the profile or `none`. |

Expand Down
15 changes: 5 additions & 10 deletions docs/nodejs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,8 @@ Returns the fastest route between two or more coordinates while visiting the way
* `options.bearings` **[Array][5]?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction.
Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`.
* `options.radiuses` **[Array][5]?** Limits the coordinate snapping to streets in the given radius in meters. Can be `null` (unlimited, default) or `double >= 0`.
* `options.hints` **[Array][5]?** Hints for the coordinate snapping. Array of base64 encoded strings.
* `options.hints` **[Array][5]?** Deprecated. This parameter is silently ignored.
* `options.exclude` **[Array][5]?** List of classes to avoid, order does not matter.
* `options.generate_hints` **[Boolean][4]** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`)
* `options.alternatives` **[Boolean][4]** Search for alternative routes. (optional, default `false`)
* `options.alternatives` **[Number][6]** Search for up to this many alternative routes.
*Please note that even if alternative routes are requested, a result cannot be guaranteed.* (optional, default `0`)
Expand Down Expand Up @@ -100,8 +99,7 @@ Note: `coordinates` in the general options only supports a single `{longitude},{
* `options.bearings` **[Array][5]?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction.
Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`.
* `options.radiuses` **[Array][5]?** Limits the coordinate snapping to streets in the given radius in meters. Can be `null` (unlimited, default) or `double >= 0`.
* `options.hints` **[Array][5]?** Hints for the coordinate snapping. Array of base64 encoded strings.
* `options.generate_hints` **[Boolean][4]** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`)
* `options.hints` **[Array][5]?** Deprecated. This parameter is silently ignored.
* `options.number` **[Number][6]** Number of nearest segments that should be returned.
Must be an integer greater than or equal to `1`. (optional, default `1`)
* `options.approaches` **[Array][5]?** Restrict the direction on the road network at a waypoint, relative to the input coordinate. Can be `null` (unrestricted, default), `curb` or `opposite`.
Expand Down Expand Up @@ -140,8 +138,7 @@ Optionally returns distance table.
* `options.bearings` **[Array][5]?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction.
Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`.
* `options.radiuses` **[Array][5]?** Limits the coordinate snapping to streets in the given radius in meters. Can be `null` (unlimited, default) or `double >= 0`.
* `options.hints` **[Array][5]?** Hints for the coordinate snapping. Array of base64 encoded strings.
* `options.generate_hints` **[Boolean][4]** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`)
* `options.hints` **[Array][5]?** Deprecated. This parameter is silently ignored.
* `options.sources` **[Array][5]?** An array of `index` elements (`0 <= integer < #coordinates`) to use
location with given index as source. Default is to use all.
* `options.destinations` **[Array][5]?** An array of `index` elements (`0 <= integer < #coordinates`) to use location with given index as destination. Default is to use all.
Expand Down Expand Up @@ -224,8 +221,7 @@ if they can not be matched successfully.
* `options.coordinates` **[Array][5]?** The coordinates this request will use, coordinates as `[{lon},{lat}]` values, in decimal degrees.
* `options.bearings` **[Array][5]?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction.
Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`.
* `options.hints` **[Array][5]?** Hints for the coordinate snapping. Array of base64 encoded strings.
* `options.generate_hints` **[Boolean][4]** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`)
* `options.hints` **[Array][5]?** Deprecated. This parameter is silently ignored.
* `options.steps` **[Boolean][4]** Return route steps for each route. (optional, default `false`)
* `options.annotations` **([Array][5] | [Boolean][4])** An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed` or boolean for enabling/disabling all. (optional, default `false`)
* `options.geometries` **[String][3]** Returned route geometry format (influences overview and per step). Can also be `geojson`. (optional, default `polyline`)
Expand Down Expand Up @@ -295,8 +291,7 @@ Right now, the following combinations are possible:
* `options.bearings` **[Array][5]?** Limits the search to segments with given bearing in degrees towards true north in clockwise direction.
Can be `null` or an array of `[{value},{range}]` with `integer 0 .. 360,integer 0 .. 180`.
* `options.radiuses` **[Array][5]?** Limits the coordinate snapping to streets in the given radius in meters. Can be `double >= 0` or `null` (unlimited, default).
* `options.hints` **[Array][5]?** Hints for the coordinate snapping. Array of base64 encoded strings.
* `options.generate_hints` **[Boolean][4]** Whether or not adds a Hint to the response which can be used in subsequent requests. (optional, default `true`)
* `options.hints` **[Array][5]?** Deprecated. This parameter is silently ignored.
* `options.steps` **[Boolean][4]** Return route steps for each route. (optional, default `false`)
* `options.annotations` **([Array][5] | [Boolean][4])** An array with strings of `duration`, `nodes`, `distance`, `weight`, `datasources`, `speed` or boolean for enabling/disabling all. (optional, default `false`)
* `options.geometries` **[String][3]** Returned route geometry format (influences overview and per step). Can also be `geojson`. (optional, default `polyline`)
Expand Down
45 changes: 5 additions & 40 deletions include/engine/api/base_api.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@
#include "engine/datafacade/datafacade_base.hpp"

#include "engine/api/json_factory.hpp"
#include "engine/hint.hpp"
#include "util/coordinate_calculation.hpp"

#include <memory>
Expand Down Expand Up @@ -61,28 +60,11 @@ class BaseAPI

const auto &snapped_location = candidatesSnappedLocation(candidates);
const auto &input_location = candidatesInputLocation(candidates);
if (parameters.generate_hints)
{
std::vector<SegmentHint> seg_hints(candidates.size());
std::transform(candidates.begin(),
candidates.end(),
seg_hints.begin(),
[this](const auto &phantom)
{ return SegmentHint{phantom, facade.GetCheckSum()}; });

return json::makeWaypoint(
snapped_location,
util::coordinate_calculation::greatCircleDistance(snapped_location, input_location),
waypoint_name,
{std::move(seg_hints)});
}
else
{
return json::makeWaypoint(
snapped_location,
util::coordinate_calculation::greatCircleDistance(snapped_location, input_location),
waypoint_name);
}

return json::makeWaypoint(
snapped_location,
util::coordinate_calculation::greatCircleDistance(snapped_location, input_location),
waypoint_name);
}

flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<fbresult::Waypoint>>>
Expand Down Expand Up @@ -127,28 +109,11 @@ class BaseAPI
INTERSECTION_DELIMITER);
auto name_string = builder->CreateString(waypoint_name);

flatbuffers::Offset<flatbuffers::String> hint_string;
if (parameters.generate_hints)
{
std::vector<SegmentHint> seg_hints(candidates.size());
std::transform(candidates.begin(),
candidates.end(),
seg_hints.begin(),
[this](const auto &phantom)
{ return SegmentHint{phantom, facade.GetCheckSum()}; });
Hint hint{std::move(seg_hints)};
hint_string = builder->CreateString(hint.ToBase64());
}

auto waypoint = std::make_unique<fbresult::WaypointBuilder>(*builder);
waypoint->add_location(&location);
waypoint->add_distance(static_cast<float>(
util::coordinate_calculation::greatCircleDistance(snapped_location, input_location)));
waypoint->add_name(name_string);
if (parameters.generate_hints)
{
waypoint->add_hint(hint_string);
}
return waypoint;
}

Expand Down
13 changes: 3 additions & 10 deletions include/engine/api/base_parameters.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,7 @@ namespace osrm::engine::api
*
* Holds member attributes:
* - coordinates: for specifying location(s) to services
* - hints: hint for the service to derive the position(s) in the road network more efficiently,
* optional per coordinate. Multiple hints can be provided for a coordinate.
* - hints: deprecated; field retained for C++ API backward compatibility only, values are ignored
* - radiuses: limits the search for segments in the road network to given radius(es) in meter,
* optional per coordinate
* - bearings: limits the search for segments in the road network to given bearing(s) in degree
Expand Down Expand Up @@ -81,9 +80,6 @@ struct BaseParameters
std::vector<std::string> exclude;
std::optional<OutputFormatType> format = OutputFormatType::JSON;

// Adds hints to response which can be included in subsequent requests, see `hints` above.
bool generate_hints = true;

// Remove waypoints array from the response.
bool skip_waypoints = false;

Expand All @@ -94,20 +90,17 @@ struct BaseParameters
std::vector<std::optional<double>> radiuses_ = {},
std::vector<std::optional<Bearing>> bearings_ = {},
std::vector<std::optional<Approach>> approaches_ = {},
bool generate_hints_ = true,
std::vector<std::string> exclude = {},
const SnappingType snapping_ = SnappingType::Default)
: coordinates(std::move(coordinates_)), hints(std::move(hints_)),
radiuses(std::move(radiuses_)), bearings(std::move(bearings_)),
approaches(std::move(approaches_)), exclude(std::move(exclude)),
generate_hints(generate_hints_), snapping(snapping_)
approaches(std::move(approaches_)), exclude(std::move(exclude)), snapping(snapping_)
{
}

bool IsValid() const
{
return (hints.empty() || hints.size() == coordinates.size()) &&
(bearings.empty() || bearings.size() == coordinates.size()) &&
return (bearings.empty() || bearings.size() == coordinates.size()) &&
(radiuses.empty() || radiuses.size() == coordinates.size()) &&
(approaches.empty() || approaches.size() == coordinates.size()) &&
std::all_of(bearings.begin(),
Expand Down
18 changes: 3 additions & 15 deletions include/engine/api/json_factory.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,7 @@
#include <string>
#include <vector>

namespace osrm::engine
{

struct Hint;

namespace api::json
namespace osrm::engine::api::json
{
namespace detail
{
Expand Down Expand Up @@ -93,22 +88,15 @@ util::json::Object makeRoute(const guidance::Route &route,
std::optional<util::json::Value> geometry,
const char *weight_name);

// Creates a Waypoint without Hint, see the Hint overload below
// Creates a Waypoint
util::json::Object
makeWaypoint(const util::Coordinate &location, const double &distance, std::string name);

// Creates a Waypoint with Hint, see the overload above when Hint is not needed
util::json::Object makeWaypoint(const util::Coordinate &location,
const double &distance,
std::string name,
const Hint &hint);

util::json::Object makeRouteLeg(guidance::RouteLeg leg, util::json::Array steps);

util::json::Array makeRouteLegs(std::vector<guidance::RouteLeg> legs,
std::vector<util::json::Value> step_geometries,
std::vector<util::json::Object> annotations);
} // namespace api::json
} // namespace osrm::engine
} // namespace osrm::engine::api::json

#endif // ENGINE_GUIDANCE_API_RESPONSE_GENERATOR_HPP_
4 changes: 0 additions & 4 deletions include/engine/api/match_parameters_tidy.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,8 +71,6 @@ inline Result keep_all(const MatchParameters &params)

if (result.was_waypoint[i])
result.parameters.waypoints.push_back(result.parameters.coordinates.size() - 1);
if (!params.hints.empty())
result.parameters.hints.push_back(params.hints[i]);

if (!params.radiuses.empty())
result.parameters.radiuses.push_back(params.radiuses[i]);
Expand Down Expand Up @@ -167,8 +165,6 @@ inline Result tidy(const MatchParameters &params, Thresholds cfg = {15., 5})

if (result.was_waypoint[i])
result.parameters.waypoints.push_back(result.parameters.coordinates.size() - 1);
if (!params.hints.empty())
result.parameters.hints.push_back(params.hints[i]);

if (!params.radiuses.empty())
result.parameters.radiuses.push_back(params.radiuses[i]);
Expand Down
Loading
Loading