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.

Note

If you are a Matrix Routing user, please see Matrix Routing Migration Guide

If you are an Isoline Routing user, please see Isoline Routing Migration Guide

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

Note

There are some input as well as output parameters that are no longer supported due to conceptual changes. These are detailed in this guide.

Authentication

Note

The app code credentials are not supported in v8. For more information on the currently available authentication methods, see the Identity & Access Management Guide.

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

Note

In Routing v8, truck parameters are deprecated. Use vehicle parameters instead. Do not use truck parameters and vehicle parameters in the same request.

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.

Note

It is paramount to monitor critical type notices when receiving a route, and to only use the route if the consequences of expected restriction violations are well understood.

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

Parameter Routing v7 Routing v8
Base URL string, https://route.api.here.com string, https://router.hereapi.com
Version string, routing/7.2 string, /v8
Resource string /calculateroute.json string, /routes

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

Routing v7 Routing v8
Parameter waypoint0 origin
Parameter waypoint<x> via
Parameter waypoint<last> destination
Format string, {lat},{lng} string, {lat},{lng}
Behavior Sets WGS-84 compliant coordinates. Sets WGS-84 compliant coordinates.

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.

Parameter Routing v7 Routing v8
mode=<routingMode> routingMode
Format string, one of fastest,shortest, balanced string, one of fast,short
Behavior Sets the routing mode. Sets the routing mode.
Note balanced mode is no longer offered.
Parameter Routing v7 Routing v8
mode=;<transportMode> transportMode
Format string, one of car,truck, pedestrian,bicycle,carHOV string, car,truck, pedestrian,bicycle,scooter
Behavior Sets the transport mode. Sets the transport mode.
Note carHOV is no longer a separate mode. For details, see the vehicle[hovOccupancy] parameter. Also, as mentioned earlier on this page, the Public Transport mode is available on a separate endpoint.

avoid[features]

mode=;;;<RouteFeatureType>=<RouteFeatureWeightType>
v7 Parameter v8 Parameter/notes
avoidAreas avoid[areas]. Bounding boxes are supported.
avoidLinks avoid[segments]
avoidSeasonalClosures avoid[features]=seasonalClosure.
avoidTurns avoid[features]=difficultTurns (only valid when transportMode=truck).
tollroad:-2 avoid[features]=tollRoad
motorway:-2 avoid[features]=controlledAccessHighway
boatFerry:-2 avoid[features]=ferry
railFerry:-2 avoid[features]=carShuttleTrain
tunnel:-2 avoid[features]=tunnel
dirtRoad:-2 avoid[features]=dirtRoad
excludeZones avoid[zoneIdentifiers]=zoneIds
excludeZoneTypes avoid[zoneCategories]=zoneCategories
allowedZones avoid[zoneCategories]=zoneCategories;exceptZoneIds=zoneIds

For more details, refer to the Developer Guide.

v7 Parameter v8 Parameter/notes
requestId Use the header X-Request-ID.
excludeCountries Use exclude[countries].
departure departureTime. If not present, the current time is used. departureTime=any will make the service not use time-dependent attributes (also disabling traffic).
arrival Use arrivalTime
alternatives No change.
metricSystem Use units.
language Use lang.
jsonCallback Replaced by Cross-Origin Resource Sharing. See CORS on Wikipedia
routeAttributes/legAttributes/linkAttributes Use spans to select the attributes of interest or return to select other results (for example, route geometry or maneuvers).
lineAttributes For the available options, see the Public Transit API.
maxNumberOfChanges For the available options, see the Public Transit API.
avoidTransportTypes For the available options, see the Public Transit API.
combineChange For the available options, see the Public Transit API.
walkRadius For the available options, see the Public Transit API.
walkSpeed Use pedestrian[speed]=<value in meters per second>.
axleCount Use vehicle[axleCount].
shippedHazardousGoods Use vehicle[shippedHazardousGoods].
limitedWeight Use vehicle[grossWeight]. Provide value in kilograms.
weightPerAxle Use vehicle[weightPerAxle]. Provide value in kilograms.
weightsPerAxleGroup Use vehicle[weightPerAxleGroup]. It is now also possible to specify weight per triple axle group (in addition to single and tandem). Provide values in kilograms.
height/width/length Use vehicle[height], vehicle[width], and vehicle[length]. Provide values in centimeters.
tunnelCategory Use vehicle[tunnelCategory].
returnElevation Use return=polyline,elevation.
customConsumptionDetails Use ev[] parameter settings. For details, refer to the Developer Guide.
truckType Use vehicle[type]. Replace truckType=truck with vehicle[type]=straightTruck, and truckType=tractorTruck with vehicle[type]=tractor, respectively.
trailersCount Use vehicle[trailerCount].
licensePlate Use vehicle[licensePlate].

Parameters Removed

The following parameters are removed in this migration.

v7 Parameter v8 notes
viewBounds Removed, as the additional shape minimization was minimal.
jsonAttributes Removed. The return parameter can be used.
representation Removed. Response content can be controlled via spans and return.
generalizationTolerances Removed. No current use cases require this parameter.
vehicleType Removed. Consumption estimation is supported by consumption model.
walkTimeMultiplier Removed. The use case can be achieved by the pedestrian[speed] parameter.
truckRestrictionPenalty Removed. In v8 if a route could not avoid truck restrictions, it is by default returned along with notices informing about violations. See more in "Conceptual Changes" section
consumptionModel Merged with ev[] parameter settings, which allow the necessary control.
resolution Removed. Shape simplification is currently not offered.
Format Removed. The response is always returned in JSON format (v8). XML is no longer supported.
adminZones Removed as it will be replaced with avoid[truckRoadType].
instructionFormat Instructions are output as text.
timeDependentRestriction (ti) Included as part of notices
timezone (tz) Removed. No use cases identified where this information is needed.
nextManeuver Removed.
startAngle Removed.
speedProfile Removed. V8 uses a single speed-profile based on speed-limits defined by the vehicle parameters provided in the request. This makes the speedProfile parameter obsolete.

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.

v7 v8
* waypoints (wp) Each section has the section departure and arrival waypoint included in it. This parameter is not configurable and is always returned. PassThrough points are not returned, though this feature is planned. Sections compose the route.
* summary (sm) The summary is per section. Contains baseDuration, duration, distance, and consumption. The following are currently not present: link flags, textual description, CO2 emission. Some of these details do not always make sense to have at the section level.
* summaryByCountry (sc) Not present. If spans are requested with spans=countryCode,length, then information about the distance in each country can be retrieved. No plans to support in any other manner.
* shape (sh) Available as flexpolyline for return.
* boundingBox (bb) Not supported. Can easily be computed by the user. Not planned.
* legs (lg) A.k.a sections. Returned by default and not configurable.
* notes (no) Returned by default, if present. Not configurable.
* lines (li) See the Public Transit API.
* routeId (ri) Renamed to routeHandle.
* groups (gr) See the Public Transit API.
* tickets (tx) See the Public Transit API.
* incidents (ic) Use incidents.

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.

v7 v8
waypoint (wp) Returned by default at the section level.
maneuvers (mn) Replaced by actions.
links (li) Replaced by spans.
length (le) Part of summary.
travelTime (tt) Part of summary.
shape (sh) Returned as a flexpolyline
indices (ix) Returned as a flexpolyline
boundingBox (bb) Not supported. Can easily be computed by the user. Not planned.
baseTime (bt) Part of summary.
trafficTime (tm) Part of summary.
summary (sm) Summary information is per section. Contains baseduration, duration and distance and consumption. Not currently present: link flags, no textual description, CO2 emission. Also, text present at section level does not always make sense.

linkAttributes

In v7, the defaults are shape, speedLimit.

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

v7 v8
consumption (cn) Supported.
dynamicSpeedInfo (ds) Supported, except for the jam factor. Jam factor can be computed easily by user from base speed and traffic speed for given segment.
flags (fl) walkAttributes, streetAttributes, carAttributes, truckAttributes
functionalClass (fc) Supported.
indices (ix) Offset (into polyline)
length (le) At the span level (request length with segmentRef)
maneuver (ma) Indirectly supported via shared offsets between actions and spans.
nextLink (nl) Not supported. Since the map is structured as segments, requesting for segmentRef in spans will return the list of segment references.
nextStopName (ns) See the Public Transit API.
publicTransportLine (pt) See the Public Transit API.
remainDistance (rd) Not supported. This value can be computed by subtracting the length of the segment iteratively from the full length of the route.
remainTime (rt) Not supported. This value can be computed by subtracting the duration of the segment iteratively from the full duration of the route.
roadName (ro) Multiple names supported, as per requested language, when requested at the span level.
roadNumber (rn) Multiple numbers supported, as per requested language, when requested at the span level.
shape (sh) Offsets are used instead.
speedLimit (sl) Supported.
truckRestrictions (tr) Not supported. This is map relevant information and it exposed by the Vector Tile API .

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.

v7 v8
position The position can be identified after decoding the polyline using a Flexible Polyline library by using action's offset attribute to index the list of decoded polyline vertices.
shape The shape is formed from the vertices in the decoded polyline and is defined by the vertex corresponding to the offset of a given action to the vertex corresponding to offset - 1 of the subsequent action.
travelTime Not needed as duration is provided.
time Not supported. For navigation use cases, this information has to be computed by the positioning system.
length Not supported. Information about length of the route-segment is returned in the instruction.
link Supported implicitly via offsets shared with spans.
publicTransportLine This is a Public Transit maneuver attribute. For details, see Public Transit.
platform This is a Public Transit maneuver attribute. For details, see Public Transit.
roadName Returned as part of turnByTurnActions.
nextRoadName Returned as part of turnByTurnActions.
roadNumber Returned as part of turnByTurnActions.
nextRoadNumber Returned as part of turnByTurnActions.
signPost Not supported.
notes Not supported. Notes are returned as the top level. The change in transport mode along the route is represented with transport parameter
action Supported, see below for details.
direction Returned as two parts direction and severity.
freewayExit Supported in instructions and not in actions.
freewayJunction Supported in instructions and not in actions.
indices Offset into the polyline.
baseTime baseDuration
trafficTime duration
waitTime This is a Public Transit maneuver attribute. For details, see Public Transit.
boundingBox Can be computed from shape.
roadShield Not supported.
shapeQuality Not supported.

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.

Action Direction Severity v7 Action
turn left light slightLeftTurn
turn left quite leftTurn
turn left heavy sharpLeftTurn
turn left NONE continue
turn middle ANY continue
turn right light slightRightTurn
turn right quite rightTurn
turn right heavy sharpRightTurn
turn right NONE continue
keep left light leftFork
keep left quite leftFork
keep left heavy leftFork
keep left NONE leftFork
keep middle light middleFork
keep middle quite middleFork
keep middle heavy middleFork
keep middle NONE middleFork
keep right light rightFork
keep right quite rightFork
keep right heavy rightFork
keep right NONE rightFork
continue ANY ANY continue
ramp left ANY leftRamp
ramp middle ANY middleRamp
ramp right ANY rightRamp
ramp NONE ANY continue
roundaboutEnter left ANY leftRoundaboutEnter
roundaboutEnter right ANY rightRoundaboutEnter
roundaboutPass left ANY leftRoundaboutPass
roundaboutPass right ANY rightRoundaboutPass
roundaboutExit left ANY leftRoundaboutExit
roundaboutExit right ANY rightRoundaboutExit
uTurn left ANY leftUTurn
uTurn right ANY rightUTurn
arrive ANY ANY arrive
exit left ANY leftExit
exit middle ANY middleFork
exit right ANY rightExit
exit NONE NONE continue
depart in combination with board and deboard ANY ANY ferry
depart not in combination with ferry routing ANY ANY depart
nameChange ANY ANY nameChange

results matching ""

    No results matching ""