/autosuggest,/discover and /browse endpoints support Search along the route use-cases through the optional route parameter. Search results are then returned with two types of distance elements:
distance: the total distance along the route plus the distance from the route to the result, and
excursionDistance: the distance from the route to the result.
Route definition
The format of the route parameter value is that of HERE flexible-polyline, extended with an additional optional w parameter specifying the width in meters from the specified route.
The value of the parameter w is the maximum distance "as the crow flies" between the search results and the polyline. Consequence: the corridor polygon in which search results are to be found is of total width 2*w. The combination of the polyline and the width forms a corridor, and all search results will be restricted to the defined corridor. The distance field value represents the sum of the distance along the polyline plus the distance from the polyline to the result as the crow flies. That distance is l1+l2+l3 in the figure below.
Note about l3 that
l3 is always such as l3 < w
excursionDistance response element is equal to 2*l3
Figure 1. polyline, corridor, width and distances
The default value for the width w is 1000 (meters). It is advised to keep the route number of points below 300 to comply with URL length of 2048 bytes.
An application using /discover would send the following query for "restaurants" in the defined route from Berlin to Hamburg, at the position 52.5308,13.3847 on that route, with a width of 1000 meters along that route:
The routes returned by industry leading services like HERE routing API are very detailed. For instance the flexible polyline string for a route between Berlin and Hamburg is about 18K bytes (about 4000 points). To be used on /discover, /autosuggest or /browse, such a route needs to be geometrically simplified, to comply with the maximum URL length of 2048 bytes supported by HERE Geocoding and Search. For this, developers should consider a Ramer–Douglas–Peucker algorithm that offers a typical O(n logn) complexity.
Note that the flexible polyline used for the above example is the result of a Ramer–Douglas–Peucker simplification applied on the polyline returned by HERE routing API for a route from Berlin to Hamburg. The epsilon used to reach a length of 1769 bytes was 0.0002.
For longer routes, it is necessary to increase epsilon. For instance the polyline returned by HERE routing for a route between New-York City and Los Angeles is about 200K characters. An epsilon of 0.015 is sufficient to reduce its sized to 1494 bytes.
route example
polyline length
points number
epsilon
reduced points number
simplified polyline length
Berlin / Hamburg
18K
4k
0.0002
368
1769
Hamburg / Marseille
104K
23k
0.005
299
1751
New-York / Los Angeles
199K
42k
0.015
235
1494
The simplification workflow for a route provided by the HERE routing API would then be:
flexible polyline decoding into a line-string of geo-coordinates
line-string simplification
simplified line-string encoding into a shorter flexible polyline
For example a python script using the HERE flexible-polyline package and the simplification package developed by Stephan Hügel (MIT license) would look like:
from flexpolyline import decode, encode
from simplification.cutil import simplify_coords
defsimplify(flex_polyline:str, epsilon:float)->str:
decoded = decode(flex_polyline)
simplified = simplify_coords(decoded, epsilon)return encode(simplified)