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.

Migrate from Isoline Routing Service v7 to Isoline Routing Service 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 Isoline Routing v7 service to switch to using the Isoline Routing v8 service for their applications. For full details, see the Isoline Routing 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

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

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.

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

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

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.

results matching ""

    No results matching ""