Implementing Search along the route
/autosuggest
,/discover
and /browse
endpoints support Search along the route use-cases through the optional route
parameter . Search results are then returned with a distance
response element representing their distance along the specified route.
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 combination of the polyline and the width forms a corridor, and all search results will be restricted to the defined corridor.
For instance adding ;w=2000
to the value of a flexible polyline changes the width of the corridor to 2 kilometers, into which all results will be located into.
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:
https://discover.search.hereapi.com/v1/
discover?apiKey={YOUR_API_KEY}
&at=52.5308,13.3847
&limit=10
&route=BF0-zgKyl2xCvCrJ2mBtwBwY9kB2xEthIyYrjDuBjlBoOpEoLNoJzE0I9KkPjeiI5JwrDzoCqdtc8H1NgKtjBsM1WuQ_yB2alkCuGlK8EpDuFUiPgV-HT0LpOkJDmD5B2dnnBmI_G8J_D0zEmW4RbiSzD6N3EuUtKqS9MsOjNsZneiyC1oE8RxY8hB1iB8tBjesJzJ8HhOuErPmC1W1FxjBzB7YD3kGiK5iFaty
BvEzlC7Nj_D1B7lBgB3rBiGj5Bq8B7tL-YhjHsM_6BiSt2Bi8Cv7F0SrrBwO_nBoMtnBiN7zBggBzuFqRrqC-LvmB8QzsB4hBrkCohB_xBkiBxnBqhBvd4hBrW2lBpRsnB_JysB1DizDhBkYlE6a3JqW3M6ZvU2pC5tC6oBziB8uB3c2kF51C4XvPyT_QmhBpnB45Bt7CmnC31CuW5f0NjYwOtfiqBn2DiVhtBoWxjB09Bjw
C-zBx5C-brmBmczcg1BruB0apbklEtiFkjB1nBwiBlhB4_BtzB8X3XyZ9hBm4Bn6CwiB7oBoWxTkZzQszCzlBuWzMge1WoclckZpgBgcxuBu1Bl3DgTnmBwaloB8V9YkbjXgb9PsKZuGwCmRgRsI4DqL1B-J3I8F_K0D5NsFtvCkJ77B2K5uB4PtyBsO7jBgVnqBqTtf6gBrtBkYtpB2Y12BqS92BuKnpBqJ5yByPt9E6Jxh
CwQ9jCmSj1ByWryBmattBqRxY4xBh9BojB33BqwElzIqV_wBwbhtCkXnzByZzrBg4BnxCymB5oCsbhiCsY3rCmNj0B2mBpwF4NhxBqXn9BkkBhrCiZ1lCqNr0B-Jz0BgMnzC4Gt-BsGrxDkC1yIqF7jCsLpnCgJlnB-NhvBkP3oBmQrkBge71B23BhuC0Std-SljBgU3tBkW_jC2gBzwEglB94D4MzhC0L9vDoNtnCyU_kC
ufpqCwQhuB0MjvBkKj1BqFhrBmDpyBqCzjIoChlC4HhpC4NnkCmRn5BgU5xBoVzpBigBzyB2QlewQ7lB0cpxCiO9gBqS_hBgkB72BiSxf0Q_kB8M9kB-dp5D-e33C0OnyByLzyByJ17BiGnjCqBrhC7BxvB3K1_DFxqC-Hp9C0I1zB-JjsB4WtqC0drlCmWzoB03CrrEqR9gB8P5kBqVxhCwShyCkN3tB6O_nBqdpjC6Qtx
BiOx5B6Ir2BoF99BM3zBxCzwBtMl0DlBzyBuCn6B-zB1nM4T_6G0FtuE8EzlCmjC7hS2GzsCqI3yF_G7-F0D54J0FzwC2O35Cw2Cv-K8xB9xHmUhpC6pBlgE6QtrC2JlqCwF9wCS1lCvCj9DwC52BuV54DsK_1D2WrjDuO7hEmenwEqIzkCmB32BjD_yBtzB_pL1EjvB_BhtB-B3iCkR3pGvBpkBnM1oDL5wB-Gv2B4iB_zE
qFjsBsC9vBnCtlCvNrxErtBrlJ1HnsDb3oB2CppBkZnkEgB_V1B_kB1DjRpH3R1JtP_M9NvWzO55B7XxYnPnchXlpBjoBnhBnrBriB97BpbjhClOtrBzOt3BjH1xBoB5hBgLzpC2DtvFqD5N6G_I85B51BwUvRoLtE2KiD4MwHqnBgkB8UqQ0EuCiChBkL_ZmIpjBuNtlBuN9R6CrMWjkB2MyB6RvH6TjiB2GnY0B9R7I5E9
I9H3CNhDyF;w=1000
&q=restaurant
This query returns the following response:
{
"items": [
{
"title": "Cô Chu",
"id": "here:pds:place:276hzqom-a51495c57f0210dc85fd26e4b796f449",
"resultType": "place",
"address": {
"label": "Cô Chu, Invalidenstraße 29, 10115 Berlin, Deutschland",
"countryCode": "DEU",
"countryName": "Deutschland",
"state": "Berlin",
"county": "Berlin",
"city": "Berlin",
"district": "Mitte",
"street": "Invalidenstraße",
"postalCode": "10115",
"houseNumber": "29"
},
"position": { "lat": 52.53112, "lng": 13.38471 },
"access": [{ "lat": 52.53104, "lng": 13.38476 }],
"distance": 36,
"categories": [{ "id": "100-1000-0000" }],
"foodTypes": [{ "id": "200-000" }, { "id": "206-000" }]
},
{
"title": "Bangaluu-Private Dining",
"id": "here:pds:place:276u33db-6943d7dab85640d3bf84eb810a46b6c3",
"distance": 34,
...
},
...
{
"title": "Bio Company Chausseestraße",
"id": "here:pds:place:276u33db-7be18fbf70df4a53ad7013794b014fea",
"distance": 119,
...
}
]
}
Route Simplification
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
def simplify(flex_polyline: str, epsilon: float) -> str:
decoded = decode(flex_polyline)
simplified = simplify_coords(decoded, epsilon)
return encode(simplified)