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.

The simplification workflow for a route provided by the HERE routing API would then be:

1. flexible polyline decoding into a line-string of geo-coordinates
2. line-string simplification
3. 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)