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 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

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)