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