Guidesv3.2 API Referencev3.1 API Reference
Guides
  1. Migration Guide

Migrate from the HERE Maps API for JavaScript version 3.1 to version 3.2

Migrate your application from the HERE Maps API for JavaScript version 3.1 to version 3.2 for continued support and feature development. This guide outlines the steps and procedures required to ensure a seamless transition between the two API versions.

Overview

The primary change between HERE Maps API for JavaScript versions 3.1 and 3.2 involves changing the default engine for map rendering.

In version 3.1, you could select between the functionally overlapping P2D, WEBGL, or HARP engines. In version 3.2, the P2D and WEBGL engines were removed with the HARP engine now being the default and only rendering engine integrated into the core (mapsjs-core.js) module. As a result, the separate harp (mapsjs-harp.js) module and mapsjs.bundle.harp.js bundle were removed.

Apart from making HARP the default engine, some legacy functionality was removed.

Migration process

The following sections provide the mandatory migration steps from version 3.1 to version 3.2 for all applications as well as the steps specific to the map rendering engine that you used in version 3.1.

Library import

To migrate to version 3.2.x.x, CDN users must fetch the library from the https://js.api.here.com/v3/3.2 address instead of from https://js.api.here.com/v3/3.1, as shown in the following for example:

<script type="text/javascript" src="https://js.api.here.com/v3/3.2/mapsjs-core.js"></script>
<script type="text/javascript" src="https://js.api.here.com/v3/3.2/mapsjs-service.js"></script>
<script type="text/javascript" src="https://js.api.here.com/v3/3.2/mapsjs-mapevents.js"></script>
<script type="text/javascript" src="https://js.api.here.com/v3/3.2/mapsjs-clustering.js"></script>
<script type="text/javascript" src="https://js.api.here.com/v3/3.2/mapsjs-data.js"></script>
<script type="text/javascript" charset="utf-8" src="https://js.api.here.com/v3/3.2/mapsjs-ui.js"></script>
<link rel="stylesheet" type="text/css" href="https://js.api.here.com/v3/3.2/mapsjs-ui.css" />
📘

Note

In version 3.2, the CDN module mapsjs-harp.js doesn't exist anymore and the HARP engine is part of the mapsjs-core.js module.

NPM users must change the version of the @here/maps-api-for-javascript package in the package.json file to 2.x.x and then import the library by using the following import statement:

import H from '@here/maps-api-for-javascript';
📘

Note

Version 3.2 doesn't have a separate mapsjs.bundle.harp.js bundle anymore.

API version upgrade

Perform the following steps to migrate your application from version 3.1 to 3.2, in no specific order:

  • Adjust the version numbers for the imported libraries as described in Library import.

  • If you pass the ppi option to H.service.Platform#createDefaultLayers, adjust its value to one of the values supported by the Raster Tile API v3: 100, 200, or 400.

  • If you pass disableLegacyMode: true to the H.data.geojson.Reader constructor, remove that option because the legacy mode is not available in version 3.2. If you don't pass the disableLegacyMode option or pass false as a value, then adjust application code to expect map objects with H.geo.Multi{Point, LineString, Polygon} geometries instead of H.map.Group, also adjust code to not access properties field returened from the getData() method.

  • If you pass an instance of H.geo.LineString to the H.map.Polygon constructor, create and pass an instance of H.geo.Polygon or H.geo.MultiPolygon instead.

  • If you use a raster layer created by H.service.Platform#createDefaultLayers and want to hide POIs, pass pois: false to createDefaultLayers method because in version 3.2 POIs are enabled by default.

  • If you pass the opt_version parameter to H.service.Platform#getRoutingService, H.service.Platform#getTrafficService or H.service.Platform#getVenuesService, there is no need to pass it anymore in version 3.2. The opt_version parameter was removed in version 3.2 and now it returns the latest version of the service class. If your application relies on functionality which was already deprecated in version 3.1, you must adjust your application to use the latest classes only.

  • If you use a layer created by H.service.Platform#createDefaultLayers, ensure that the layer you need still exists in version 3.2 because some layers were removed. The following list provides the removed layers and suggest their replacements:

    • raster.normal.xbase - Use raster.normal.base instead.

    • raster.normal.xbasenight - Use raster.normal.basenight instead.

    • raster.normal.trafficincidents and vector.normal.trafficincidents - You can either use vector.traffic.map layer which contains both traffic flow and traffic incidents or create and use a custom layer instance with traffic incidents only, as shown in the following example:

      // If you use fixed version of the library then replace 3.2 in the URL below with the version you use, e.g. 3.2.0.0:
const style = new H.map.render.harp.Style("https://js.api.here.com/v3/3.2/styles/harp/oslo/normal.day.json");
map.addLayer(platform.getTrafficVectorTileService({layer: "incident"}).createLayer(style));

    • raster.normal.transit - You can use vector.normal.map as a base layer and enable public transit feature. For more information on enabling features and modes, see the description of the H.map.render.harp.Style#setEnabledFeatures method in the API Reference.

    • raster.terrain.xbase - Use raster.terrain.base instead.

Migration steps specific to 3.1 HARP users

If your application uses the HERE Maps API for JavaScript 3.1 with the engineType: H.Map.EngineType.HARP, follow the instructions in API version upgrade. No additional steps are required.

Migration steps specific to 3.1 WEBGL and P2D users

If your application uses the HERE Maps API for JavaScript 3.1 with the engineType: H.Map.EngineType.WEBGL or engineType: H.Map.EngineType.P2D then in addition to adjustments described in API version upgrade, perform the following updates:

  • If you are using a layer created by H.service.Platform#createDefaultLayers, ensure that the layer you need still exists. The following list provides the removed layers as well as the replacement suggestions:

    • raster.normal.metaInfo - You can use the vector.normal.map layer instead. Vector layers contain meta information, therefore additional meta info layer is not required anymore.

    • vector.normal.truck - You can use vector.normal.logistics layer instead and enable the vehicle restrictions feature.

    • vector.normal.traffic - You can either use vector.traffic.map layer instead, that layer contains both traffic flow and traffic incidents, or create and use a custom layer instance with traffic flow only, as shown in the following example:

      // If you use fixed version of the library then replace 3.2 in the URL below with the version you use, e.g. 3.2.0.0:
const style = new H.map.render.harp.Style("https://js.api.here.com/v3/3.2/styles/harp/oslo/normal.day.json");
map.addLayer(platform.getTrafficVectorTileService({layer: "flow"}).createLayer(style));

  • The HERE Maps API for JavaScript 3.2 uses the HARP styling system. Style configurations created for the WEBGL engine are not compatible with version 3.2. If you use version 3.1 with WEBGL custom styles, you can recreate and export the corresponding custom styles by using the HERE Style Editor as shown in the following example:

    const style = new H.map.render.harp.Style("PATH/TO/YOUR/STYLE");
map.setBaseLayer(platform.getOMVService().createLayer(style));

Next steps

To explore the design and other features of the HERE Maps API for JavaScript, see the API Reference.

Updated this month