Introduction

We’re very excited to announce and present a new set of HERE Location Services that are leveraging the HERE platform and can be easily accessed through our Developer Portal at developer.here.com. These newly released versions of HERE Location Services provide a unified API framework, while leveraging the HERE platform, making it easy and efficient for any customer to adopt the breadth of our Location Services offering and beyond. As a customer of our Location Services you can now benefit from a set of redesigned and aligned APIs, as well as a streamlined architecture with compatibility across all location services, as they’re sharing the same HERE map data, authentication and authorization methods as well as API specification. In addition, the newly released HERE Location Services are leveraging fresher map content through higher map update frequency and faster availability of new regions (e.g. such as the recently integrated high detail map of Japan) realized today through the HERE platform.

With the new service framework in place, we are also on our way to delivering new functionalities that will only become available through the newly released HERE Location Services.

All our customers today can benefit from these new features and capabilities when accessing the newest versions of the HERE Location Services. If you’re already using token or API key authentication, then no change regarding access credentials is needed. If however, you’re still using app_id and app_code, please check out the documentation posted at https://developer.here.com/documentation/identity-access-management where you will find information on how to create and use new credentials.

We hope you are as excited as we are! We encourage all our customers to explore and evaluate our new services while getting themselves familiarized with the new features and functions they have to offer.

The new Routing API v8 provides new modes and features such as these:

• Two-wheeler routing using specific road segments and adopted speed profiles
• Charge-aware EV routing for finding fastest routes considering optimized charging stops
• Performance and quality improvements to core routing algorithm
• Service offering also in geography of Japan

Migrate from Routing Services v7 to Routing Services v8

HERE's Routing v7 services are planned to be deprecated over the course of the next few months and the services are in maintenance mode. This guide is provided to help users of the Routing v7 services to switch to using the Routing v8 services for their applications.

For full details, see the Routing v8 Developer Guide and API Reference.

Preparation

The following general actions must be taken to complete the migration:

• change authentication method (if applicable)
• update request parameters
• update handling of new output format

Authentication

For more information on the available usage plans and limits, see Pricing and Plans.

Conceptual Changes

Map Information

The underlying map used by the Routing service in the v8 service is HERE Map Content. This maps follows the Topology Model. Consequently, there is no concept of links and link attributes in v8.

This leads to differences in how the route-relevant map information can be returned. The route response in v8 is comprised of one or more Sections. It may have Spans, if route-related attributes are requested.

Spans, in general, present a compact representation of route attributes and replace the linkAttribute responses. Various route and leg attributes can now be specified via the return parameter.

More details are available in the Routing API v8 Developer Guide.

Public Transit Routing

Public Transit routing was offered as a mode in Routing v7 service (mode=;publicTransportTimeTable or mode=;publicTransport), as well as a separate Public Transit v3 service with a dedicated endpoint: https://transit.ls.hereapi.com. In v8, the structure is simplified, and the dedicated Public Transit v8 service (https://transit.router.hereapi.com) is the only way to access this functionality. For more information, see the documentation for the Public Transit API v8 service.

Routes which violate truck restrictions

Routing v7 had a strict approach to truck restrictions. There, no route which violated some truck restriction(s) was ever returned. It was possible to change this behavior with truckRestrictionPenalty parameter, but even then Routing v7 provided only a generic notice: Code: routingOptionViolated, Text: truckRestriction.

If Routing v8 cannot find any route that obeys all specified options and vehicle parameters and that avoids all applicable restrictions, by default, the response will contain a route that violates some restrictions. The response will also contain a set of critical notices explaining which restrictions could not be avoided. In some areas, this is not possible, for example in Romania, where almost all of the main roads have a 11.5t per axle restriction.

Migration of the Calculate Route Request

This section covers the actions that must be taken to migrate a v7 Calculate Route request to a v8 Routing request.

For more details about the types or specification of parameters, see the Routing API v8 Developer Guide.

Request

This section describes changes in the request.

Parameters Added

This migration introduces new parameters, return and spans for the new conceptual changes described above.

Parameters Changed

The following parameters are changed in this migration.

Base URL, Version, Resource

waypoint<x> vs origin,via,destination

This migration splits the waypoint<x> parameter (v7) into a few separate specific waypoint types (v8). waypoint0 is referred to as origin in v8.

An intermediate waypoint<x> should be specified as via (v8). When multiple intermediate points need to be specified, use multiple via=<> parameters.

The last waypoint<n> (that is, the destination) parameter in (v7) is now called destination (v8).

mode split into routingMode, transportMode, and avoid[features]

This migration splits the mode parameter (v7) into a few separate specific options (v8). For RouteFeatureType and RouteFeatureWeightType, use avoid[features]. The options (-1 and -3) were not providing sufficient value or user experience according to usage statistics and feedback, therefore v8 offers only the equivalent of RouteFeatureWeightType=-2 (softExclude).

Traffic is used in route calculations by default, unless departureTime is set to any, so TrafficMode is no longer offered as a separate option. In v7, the setting looks like mode=<routingMode>;<transportMode>;<trafficMode>;<RouteFeatureType>=<RouteFeatureWeightType> For individual parameters in v8, see below.

avoid[features]

mode=;;;<RouteFeatureType>=<RouteFeatureWeightType>

For more details, refer to the Developer Guide.

Parameters Removed

The following parameters are removed in this migration.

Response

This section describes changes in the response.

Response Structure

The route response in Routing v7 was structured hierarchically as Route -> Leg -> Maneuver -> Link, book-ended by meta information and route summary information. Many of the details could be included or excluded in the request but there were also defaults set for the various levels of hierarchical information, such as RouteAttributes and ManeuverAttributes.

The route response in Routing v8 is structured hierarchically as routes -> sections and meta information. actions, summary, polyline (Geometry), notices, and spans (if requested) are nested inside each corresponding section.

The response information in v8 is configurable, which is similar to v7, but any route information, including summary information like duration and distance or the route shape, is only returned when requested explicitly.

If geometry is desired, it must be enabled with return=polyline. The resulting geometry is encoded as a Flexible Polyline. Decoders are available in several major languages.

Conversely, additional notices on the route, like options that were violated, were not returned by default in v7 and consumers had to request the notes at route or leg levels to get this information. This information is now provided by default as part of the violating route section (under notices).

routeAttributes

In v7, by default waypoints, summary, legs are returned, unless other route attributes are explicitly requested. Additionally, if publicTransport or publicTransportTimeTable mode is used, lines also are returned.

In v8, sections conceptually replace legs. They are always a part of the response. As sections comprise of origin and destination waypoints, these are also always returned. summary has to be requested using the return parameter, as can other information, too.

legAttributes

In v7, this defaults to maneuvers, waypoint, length, travelTime.

In v8, as mentioned above, section is an entity equivalent to leg. If nothing is explicitly requested, then the section only has coordinate information about the departure and arrival waypoints and the transport mode used. The change in transport mode along the requested route is also specified in the transport parameter. If summary is requested, then the section duration (with and without traffic) and length are returned.

linkAttributes

In v7, the defaults are shape, speedLimit.

In v8, segmentRef is returned instead of PVID. spans conceptually replace link attributes.

lineAttributes

For the available options, see the Public Transit API.

maneuverAttributes

In v7, the defaults are position, length, travelTime.

In v8, these parameters are not configurable and separated into actions and turnbyturnActions.

The action enumeration was changed from a simple enumeration (v7) into 3 granular attributes: action, direction and severity. The following table shows how combinations of these values correspond to v7 enumeration values. Note that ANY, and NONE are not part of enumerations, but indicate that either all values behave like that, or that a missing value behaves like that.