Isoline Routing Migration Guide

Feedback

Last UpdatedMay 19, 2025
7 minute read

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 you’re still using app_id and app_code, see the Identity and Access Management Developer Guide 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.

Migrate from Isoline Routing Service v7 to Isoline Routing Service v8

HERE 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 Isoline Routing v7 service to switch to using the Isoline Routing v8 service for their applications. For full details, see the Isoline Routing API v8 Developer Guide and API Reference.

Note

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

If you are a Matrix Routing user, please see Matrix 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.

Migration of the Calculate Isoline Request

This section highlights the important changes necessary to migrate to Isoline Routing v8.

Request

Parameters Added

No parameters have been added in the migration.

Parameters Changed

Base URL, Version, Resource

Search:

Parameter	Calculate Isoline (v7)	Isoline Routing (v8)
Base URL	string, `https://isoline.route.ls.hereapi.com/routing`	string, `https://isoline.router.hereapi.com`
Version	string, `/7.2`	string, `/v8`
Resource	string, `/calculateisoline.json`	string, `isolines`

Authentication

	Isoline (v7)	Isoline Routing (v8)
Format	string, `app_id/app_code`	`apiKey` parameter or OAuth bearer token in the request headers.

For more information on the currently available authentication methods, see the Identity and Access Management Developer Guide.

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

Request ID vs HTTP header X-Request-ID

The migration replaces the requestId query parameter with the HTTP header X-Request-ID.

	`requestId` (v7)	`X-Request-ID` (v8)
Format	string	string in HTTP header

`start` vs `origin`

The migration replaces the start parameter with origin. Simple coordinates still work, check the API specification for the expected format of the additional waypoint matching features.

For examples, see Calculate distance-based isoline routing and Waypoint.

	`start` (v7)	`origin` (v8)
Format	string, `{lat, long}`	`waypoint` object.

`destination`

The migration changes the data-type of the destination parameter. Simple coordinates still work, check the API specification for the expected format of the additional waypoint matching features.

	`destination` (v7)	`destination` (v8)
Format	string, `{lat, long}`	`waypoint` object.

`departure` vs `departureTime`

	`departure` (v7)	`departureTime` (v8)
Format	`xs:dateTime`	RFC 3339, (`YYYY-mm-ddTHH:MM:SS(.NNN)(Z\|+/-AA:BB)`) or string, `any` will skip use of time-dependent attributes (such as traffic)

`arrival` vs `arrivalTime`

	`arrival` (v7)	`arrivalTime` (v8)
Format	`xs:dateTime`	RFC 3339, (`YYYY-mm-ddTHH:MM:SS(.NNN)(Z\|+/-AA:BB)`) or string, `any` will skip use of time-dependent attributes (such as traffic)

`range` and `rangeType` vs `range` object

The migration replaces range and rangeType with the range object which has two fields, range[type] and range[values].

`type`

	`rangeType` (v7)	`range[type]` (v8)
Format	string, allowed values are `distance`, `time`, `consumption`	string, allowed values are `distance`, `time`,`consumption`.

`values`

	`range` (v7)	`range[values]` (v8)
Format	string, comma-separated list with units based on `rangeType`	string, comma-separated list with units based on `range[type]`

`mode` vs `routingMode`, `transportMode` & other parameters

The migration replaces the composite mode (string, Type + [TransportModes] + [TrafficMode] + [Feature]) field with multiple independent fields.

`Type`

	`Type` (v7)	`routingMode` (v8)
Format	string, allowed values are `fastest`, `shortest`, `balanced`	string, allowed values are `fast` and `short`

`TransportMode`

	`TransportModes` (v7)	`transportMode` (v8)
Format	string, supported types are `car`, `pedestrian`, `truck`	string, supported types are `car`, `pedestrian` and `truck`

`TrafficMode`

	`TrafficMode` (v7)	removed (v8)
Format	string, supported types are `enabled`, `disabled`, `default`	traffic is always enabled unless `departureTime=any` or `arrivalTime=any` is used.

`Feature`

Search:

	`Feature` (v7)	`Avoid[feature]` (v8)
Format	string, RouteFeatureType:RouteFeatureWeightType	string, comma-separated list of route features to be avoided. For the list of supported features, see the API specification.
Parameter	tollroad:-2	avoid[features]=tollRoad
Parameter	motorway:-2	avoid[features]=controlledAccessHighway
Parameter	boatFerry:-2	avoid[features]=ferry
Parameter	railFerry:-2	avoid[features]=carShuttleTrain
Parameter	tunnel:-2	avoid[features]=tunnel
Parameter	dirtRoad:-2	avoid[features]=dirtRoad
Parameter	avoidTurns	avoid[features]=difficultTurns (only valid when transportMode=truck)

`quality` vs `optimizeFor`

The quality parameter is renamed to optimizeFor. This parameter specifies how isoline calculation is optimized and has the following values:

quality: calculation focused on quality, that is, the graph used for isoline calculation has higher granularity generating a more precise isoline.
performance: calculation of isoline is performance-centric, the quality of isoline is reduced in favor of better performance.
balanced: calculation of isoline takes a balanced approach, averaging between quality and performance.

Default behavior : balanced

Search:

`quality` (v7)	`optimizeFor` (v8)
quality=1	optimizeFor=quality
quality=2	optimizeFor=balanced
quality=3	optimizeFor=performance

Maxpoints

	`maxPoints` (v7)	`shape[maxPoints]` (v8)
Format	integer, maxpoints=100	integer, shape[maxPoints]=100

Resolution

The migration changes the unit of the resolution parameter and it is now three times as precise. To match the behaviour of v7, multiply the v7 input value by 3.

	`resolution` (v7)	`shape[maxResolution]` (v8)
Format	integer, resolution=100	integer, shape[maxResolution]=100

Note

Quality and correctness of isoline degrades as the maxPoints value is decreased. Hence, in v8, we have limited the value to be not less than 30 max points. It is recommended to use a maxPoints value greater than 100 for optimal quality isolines.

EV Parameters

	`customConsumptionDetails` (v7)	`ev[]` (v8)
Format	customConsumptionDetails	Use `ev[]` parameter settings. For details, see the Developer Guide.

Truck Specific Parameters

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

Search:

`V7 Parameter`	`V8 Parameter`
axleCount	Use vehicle[axleCount]
shippedHazardousGoods	Use vehicle[shippedHazardousGoods]
limitedWeight	Use vehicle[grossWeight]. Provide value in kilograms
weightPerAxle	Use vehicle[weightPerAxle]
height/width/length	Use vehicle[height], vehicle[width], and vehicle[length]. Provide values in centimeters.
tunnelCategory	Use vehicle[tunnelCategory]
truckType	Use vehicle[type]
trailersCount	Use vehicle[trailerCount]

Parameters Removed

Search:

Parameter	v7 Behavior	v8 Behavior
`singleComponent`	If set to `true`, the isoline service will always return a single polygon instead of creating a separate polygon for each ferry-separated island. The default value is `false`.	Separated regions/islands will always be returned as multiple polygons.
`resolution`	Allows to specify the level of detail needed for the isoline polygon. The unit is meters per pixel. Higher resolution may cause increased response time from the service.	The current behavior is equivalent to not specifying the parameter in v7.2
`speedProfile`	Removed. It is expected that in the future all vehicle parameters should be taken into account to adjust the real vehicle speed.
`consumptionModel`	The service allows you to specify vehicle specific parameters, which are then used to calculate energy consumption for the vehicle on a given route.

Format

This migration removes the Format parameter (v7). The response is always returned in JSON format (v8). XML is no longer supported.

Response

This section describes changes in the response.

Response Structure

The geocoordinates in the returned isolines are encoded as Flexible Polylines. Decoders are available in the repository for several popular programming languages.

Parameters Added

The following parameters were added to the response:

notices : Describe any issues that may have occurred while generating the requested isoline.

Parameters Changed

Search:

v7 Behavior	v8 Behavior
`center` and `start`/`destination`	Replaced by `departure` or `arrival` depending on whether the user has provided the `origin` or `destination` request parameter. These parameters are objects describing the `Time` and `Place` of departure or arrival respectively.
`isoline`	Replaced with `isolines`, which is an array of elements, one for each range specified by the user.
`range`	Replaced with `range` object defining the `type` and `value` of the range used for an element in the `isolines` array.
`component`	Replaced with `polygons`, a list of polygons defining the isoline for a given `range`. Each `polygon` has an `outer` element, which is list of geo-coordinates defining the outer boundary of the isoline. The geocoordinates are encoded as Flexible Polylines.
`Connection`	The connections now refer to the connected elements of the `polygons` array by array index as `fromPolygonIndex` and `toPolygonIndex`. The shape of the connection is defined by `shape`. It is a sequence of geocoordinates, which are also encoded as Flexible Polylines.

Related Publications

Was this article helpful?

Yes No

HERE Isoline Routing API v8 - Migration Guide

Filters

Product category

Technology

Doc type

Version

Product lifecycle

HERE Isoline Routing API v8 - Migration Guide: Isoline Routing Migration Guide

Migrate from Isoline Routing Service v7 to Isoline Routing Service v8

Note

Preparation

Note

Migration of the Calculate Isoline Request

Request

Parameters Added

Parameters Changed

Base URL, Version, Resource

Authentication

Request ID vs HTTP header X-Request-ID

start vs origin

destination

departure vs departureTime

arrival vs arrivalTime

range and rangeType vs range object

type

values

mode vs routingMode, transportMode & other parameters

Type

TransportMode

TrafficMode

Feature

quality vs optimizeFor

Maxpoints

Resolution

Note

EV Parameters

Truck Specific Parameters

Parameters Removed

Format

Response

Response Structure

Parameters Added

Parameters Changed

In This Article

Related Publications

`start` vs `origin`

`destination`

`departure` vs `departureTime`

`arrival` vs `arrivalTime`

`range` and `rangeType` vs `range` object

`type`

`values`

`mode` vs `routingMode`, `transportMode` & other parameters

`Type`

`TransportMode`

`TrafficMode`

`Feature`

`quality` vs `optimizeFor`