Waypoints overview

A waypoint is a location that the requested route must traverse. The origin and destination of a route are waypoints themselves. Every route must have at least two waypoints: origin and destination.

A route can also have several intermediate waypoints, which are locations between the origin and the destination that the route goes through in the specified sequence.

Intermediate waypoints are specified using the via parameter.

Intermediate waypoint types

There are two types of intermediate waypoints:

A stopover point: a waypoint at which the journey stops for some time before it continues. This is the default setting for all intermediate waypoints. Can be enabled explicitly through the passThrough=false option.
A passthrough point: a waypoint that doesn't stop the journey, changes the shape of the route only. Enabled through the passThrough=true option.

Waypoint options

In addition to WGS84 coordinates, a waypoint incorporates several other options and details, related to either the physical location point or to the stop itself.

Examples:

Stopover time
Navigational hints
Maneuver instructions

For a full list of waypoint options, refer to the HERE Routing API v8 API reference.

For related sample requests, see these tutorials:

Route through intermediate waypoints

To add a waypoint to a route, specify it using the via parameter in your request.

When you add stopover via waypoints (passThrough=false), the route is divided into the following sections:

From the origin to the first via
To any subsequent via, for every point in the requested order
From the last via until the destination

When the waypoints don't introduce stops (passThrough=true), the API:

Doesn't split the route into sections.
Avoids changing the direction of travel.

You can add the return=passthrough parameter to a route request to get information about passthrough waypoints in the response. This includes the location to which the passthrough waypoint was matched, and an offset into the polyline, if the polyline was requested for that route.

For sample requests that demonstrate waypoint calculation, see these tutorials:

Matching waypoints

The Routing API matches each requested waypoint location to a navigable location on the map. Waypoint matching depends on various waypoint parameters.

There are two waypoint matching strategies for a waypoint. The strategies are enabled using these parameters:

radius parameter: matches the waypoint to all segments in the set radius and allows the router to select the one that is optimal for the route.
snapRadius parameter: matches the waypoint to the closest, most "significant" road in the set radius.

These parameters are mutually exclusive on a per-waypoint level. You can use radius for one waypoint and snapRadius for another, but you can't set them both for a single waypoint.

To learn more, see Set waypoints based on UI interactions

`location` and `originalLocation`

The matched location of a waypoint can be different from the original location requested. The API response contains both the original requested location and the matched location:

location is the navigable location of the waypoint used in route calculation.
originalLocation is the original location provided in the API request.

See this example excerpt of a response with location and originalLocation:

"sections": [
  {
    "departure": {
      ...
    },
    "arrival": {
      "time": "2024-09-05T09:47:46+02:00",
      "place": {
        "type": "place",
        "location": {
          "lat": 52.5242323,
          "lng": 13.4301462
        },
        "originalLocation": {
          "lat": 52.52426,
          "lng": 13.43
        },
        "waypoint": 0
      }
    },
    ...
  }
]

Maximum number of waypoints

The maximum number of waypoints for a route is limited by the maximum length of the HTTP request. Depending on the number of options and their textual length, the number of waypoints you can fit in a request can change.

It's recommended to add no more than 100 waypoints to a single route request.

Route matching

To realize a route matching use case and re-create routes with coordinates coming from a GPS trace or an existing route, you need a high number of waypoints. To achieve this, use the /import endpoint, as it supports a much larger number of points in the input.

To learn more about /import endpoint, see How to import a route from traces.