Migration to the Maps API for JavaScript 3.1

This section outlines the migration path from HERE Maps API for JavaScript 3.0 to version 3.1 and describes in greater details the backward-incompatible changes. For more details about API versioning, see API Versions.

Version 3.1 of Maps API for JavaScript introduces the new default WebGL-based rendering engine that provides efficient vector rendering, increases map performance and gives richer experience for developer and the end user. The new rendering engine brings a number of changes in how API behaves as well as it shifts a set of functionalities related to the 2D HTML5 Canvas engine to the "legacy" modules.

API Key Instead of "app_id" and "app_code"

The HERE Maps API for JavaScript version 3.1. introduces a new way to authenticate the application. Instead of the app_id and app_code pair, the HERE Maps API for JavaScript uses the apikey. The code below shows how to instantiate H.service.Platform in the new version of the API:

var platform = new H.service.Platform({
  'apikey': '{YOUR_API_KEY}'
});

Legacy Modules

In order to enable smooth transition from version 3.0 to 3.1, the HERE Maps API for JavaScript has two auxiliary modules. These modules ensure that applications that do not have access to the latest browser technology still can benefit from the HERE services. The following modules were added:

mapsjs-core-legacy.js - brings HTML5 canvas rendering engine and its associated functionality
mapsjs-service-legacy.js - provides the access to the legacy platform services (for example, HTML5 meta-info tiles)

In order to use the modules, just include them on the page. Be sure to include these files after the module they depend on. For example:

<!DOCTYPE html>
  <html>
    <head>
      ...
      <meta name="viewport" content="initial-scale=1.0,
        width=device-width" />
      <script src="https://js.api.here.com/v3/3.1/mapsjs-core.js"
        type="text/javascript" charset="utf-8"></script>
      <script src="https://js.api.here.com/v3/3.1/mapsjs-core-legacy.js"
        type="text/javascript" charset="utf-8"></script>
      <script src="https://js.api.here.com/v3/3.1/mapsjs-service.js"
        type="text/javascript" charset="utf-8"></script>
      <script src="https://js.api.here.com/v3/3.1/mapsjs-service-legacy.js"
        type="text/javascript" charset="utf-8"></script>
      ...
    </head>

Note how *-legacy modules immediately follow core and service modules.

WebGL as a Default Engine

The HERE Maps API for JavaScript version 3.1 contains a new default rendering engine. The engine uses an HTML5 WebGL canvas element and enables rendering of rich and customizable vector maps. The engine is capable of rendering both vector and raster data, thus, the changes become automatic for the application that utilizes the JavaScript API. However, if the base layer in use does not send CORS requests, this might affect the application. You can still use the HTML5 canvas 2D rendering engine if the application cannot be run in the modern browser that supports WebGL rendering. In order to make the most of the WebGL engine, use the new vector tiles.

In the Maps API for JavaScript version 3.0, the map with raster tiles was initialized as follows:

// Obtain the default map types from the platform object:
var defaultLayers = platform.createDefaultLayers();

// Instantiate (and display) a map object:
var map = new H.Map(
    document.getElementById('mapContainer'),
    defaultLayers.normal.map,
    {
      zoom: 10,
      center: { lat: 52.5, lng: 13.4 }
    });

The snippet below shows how to switch to the vector tiles:


// Obtain the default map types from the platform object:
var defaultLayers = platform.createDefaultLayers();

// Instantiate (and display) a map object:
var map = new H.Map(
    document.getElementById('mapContainer'),
    defaultLayers.vector.normal.map,
    {
      zoom: 10,
      center: { lat: 52.5, lng: 13.4 }
    });

The snippet below shows how to use the canvas 2D rendering engine in supported legacy browsers:

// Obtain the default map types from the platform object:
var defaultLayers = platform.createDefaultLayers();

// Instantiate (and display) a map object:
var map = new H.Map(
    document.getElementById('mapContainer'),
    defaultLayers.raster.normal.map,
    {
      zoom: 10,
      center: { lat: 52.5, lng: 13.4 },
      engineType: H.map.render.RenderEngine.EngineType.P2D
    });

Default Layers Collection

The structure of the default layers collection created by the method H.service.Platform#createDefaultLayers reflects the changes in rendering. This collection holds the set of the base layers and overlays and provides an easy way to change the appearance of the map.

The following pseudocode demonstrates how the collection of the default layers was structured in the Maps API for JavaScript version 3.0:

{
incidents: <Layer>,
normal: {
  base: <Layer>,
  basenight: <Layer>,
  labels: <Layer>,
  map: <Layer>,
  mapnight: <Layer>,
  metainfo: <Layer>,
  panorama: <Layer>,
  panoramanight: <Layer>,
  traffic: <Layer>,
  trafficnight: <Layer>,
  transit: <Layer>,
  xbase: <Layer>,
  xbasenight: <Layer>
},
satellite: {
  base: <Layer>,
  labels: <Layer>,
  map: <Layer>,
  metainfo: <Layer>,
  panorama: <Layer>,
  traffic: <Layer>,
  xbase: <Layer>,
},
terrain: {
  base: <Layer>,
  labels: <Layer>,
  map: <Layer>,
  metainfo: <Layer>,
  panorama: <Layer>,
  traffic: <Layer>,
  xbase: <Layer>,
},
venues:  <Layer>
}

Version 3.1 of Maps API for JavaScript introduces new vector layers that can be used only with the WebGL rendering engine. This changes affected the structure of the default layers collection. The collection now consists of two groups: vector and raster. The raster group of layers can be used both with the HTML5 canvas rendering and the WebGL rendering, while the vector group contains the layers used only with the WebGL rendering. The follow pseudocode demonstrates the new structure of the object:

{
raster: {
  normal: {
    base: <Layer>,
    basenight: <Layer>,
    labels: <Layer>,
    map: <Layer>,
    mapnight: <Layer>,
    trafficincidents: <Layer>,
    transit: <Layer>,
    xbase: <Layer>,
    xbasenight: <Layer>
  },
  satellite: {
    base: <Layer>,
    labels: <Layer>,
    map: <Layer>,
    xbase: <Layer>
  },
  terrain: {
    base: <Layer>,
    labels: <Layer>,
    map: <Layer>,
    xbase: <Layer>
  }
},
vector: {
  normal: {
    map: <Layer>,
    traffic: <Layer>,
    trafficincidents: <Layer>
  }
}
}

The changes in the structure of the default layers collection affect the way H.ui.MapSettingsControl is created. The previous version of the API used the code below to create a custom map settings control:

// 'maptypes' variable holds the result of the H.service.Platform#createDefaultLayers call
var mapSettings = new H.ui.MapSettingsControl({
  alignment: 'top-right',
  entries: [{
    name: 'Normal map',
    mapType: maptypes.normal
  }]
});
ui.addControl('mapsettings', mapSettings);

In the new version of the API, the options parameter has been changed to accept an array of baseLayers with the associated labels defined as an H.ui.MapSettingsControl.Entry typedef:

// 'maptypes' variable holds the result of the H.service.Platform#createDefaultLayers call
var mapSettings = new H.ui.MapSettingsControl({
  alignment: 'top-right',
  baseLayers: [{
  label: 'Normal map',
  layer: maptypes.raster.normal.map
  }]
});
ui.addControl('mapsettings', mapSettings);

Asynchronous "getObjectAt" Interface

The signature and behavior of the H.Map#getObjectAt method fetching map objects at the given XY screen coordinate was changed. In version 3.1 of the API, the method is asynchronous and accepts a callback as the third parameter. For example, in the old version, it was possible to get the map object synchronously:

// Provided that map is instantiated and there are some markers
// on the map that must be inspected.
var obj = map.getObjectAt(0, 0);
if (obj && obj instanceof H.map.Marker) {
    console.log(obj.getPosition());
}

With the new version, the same code should be executed in the callback:

// Provided that map is instantiated and there are some markers
// on the map that must be inspected.
map.getObjectAt(0, 0, (obj) => {
    if (obj && obj instanceof H.map.Marker) {
        console.log(obj.getGeometry());
    }
});

"LookAt" interface

The functionality related to the H.map.ViewModel.CameraData interface was deprecated. Similar functionality is provided by methods related to H.map.ViewModel.ILookAtData. The following methods are no longer available:

H.map.ViewModel#getCameraData
H.map.ViewModel#setCameraData
H.Map#screenToCameraData

The deprecated methods were replaced by the following methods, respectively:

H.map.ViewModel#getLookAtData
H.map.ViewModel#setLookAtData
H.Map#screenToLookAtData

The method H.Map#getCameraDataForBound was deprecated and removed. The corresponding functionality is available through the H.map.ViewModel.ILookAtData#bounds property containing the geometry that represents the visible bounds including the tilt and rotation of the map. The same is applicable to the deprecated methods H.map.ViewModel#setZoom and H.map.ViewModel#getZoom. Their functionality is now achievable through the H.map.ViewModel.ILookAtData#zoom property.

The changes in the LookAt interface also affected the H.Map class. The methods H.Map#setViewBounds, H.Map#getViewBounds and H.Map#getCameraDataForBounds were deprecated, and now direct calls to the H.map.ViewModel should be used instead.

Fractional Zoom Levels

The new rendering engine of HERE Maps API for JavaScript supports fractional zoom levels giving the end user better control over the map. The fractional zoom levels are enabled by default. When necessary, for example in case of a raster-based overlay or legacy application, you can disable this feature. The following code snippet demonstrates how to disable fractional zoom levels on a H.mapevents.Behavior instance and UI ZoomControl.

// Provided that the map, UI and mapevents behavior are instantiated

// disable fractional zooming for Behavior
behavior.disable(H.mapevents.Behavior.Feature.FRACTIONAL_ZOOM);

// instantiate H.ui.ZoomControl with the disabled fractional zooming
// and add it to the UI
var zoomControl = new H.ui.ZoomControl({fractionalZoom: false});
ui.addControl('zoom', zoomControl);

"StreetLevel" and "Places" Modules

In version 3.1 of HERE Maps API for JavaScript, the module responsible for the StreetLevel Imagery (mapsjs-pano.js) and the dedicated Places (mapsjs-places.js) module are deprecated. While the Places REST API functionality is available through the corresponding classes in mapsjs-service.js module, StreetLevel Imagery was deprecated and removed from the JavaScript API. The associated functions switching the render engine, such as H.Map#event:enginechange and H.Map#setEngineType, were removed together with the StreetLevel UI element (H.ui.Pano).

Traffic Incidents and Traffic Flow Service

H.service.TrafficIncidentsProvider and H.service.TrafficIncidentsService were renamed and moved into the new namespace: H.service.traffic.incidents.Provider and H.service.traffic.Service, correspondingly. The functionality of these classes remained unchanged.

Besides, version 3.1 of HERE Maps API for JavaScript offers a new recommended way to display traffic flow information provided by the Traffic REST API on the map compatible with the new WebGL rendering engine. While in the old approach the data was pre-rendered as an image on the server side, the new way uses vector rendering enabling interactions with the rendered data. In the following code sample, a new instance of the Traffic service is created and then used to create a Traffic Flow Provider that is used to display data on the map.

// Provided that map and platform objects are instantiated.
// Create a traffic service and a corresponding provider.
var service = platform.getTrafficService()
var provider = new H.service.traffic.flow.Provider(service)

// Create a tile layer that can be added to the map
var layer = new H.map.layer.TileLayer(provider);
map.addLayer(layer);

Geo Shapes and Map Objects

The following methods related to the calculation of the geometries bounding box were renamed, the signature of the methods remaining unchanged:

H.geo.AbstractGeometry#getBounds renamed to H.geo.AbstractGeometry#getBoundingBox
H.geo.Point#getBounds renamed to H.geo.Point#getBoundingBox
H.geo.Rect#getBounds renamed to H.geo.Rect#getBoundingBox
H.geo.LineString#getBounds renamed to H.geo.LineString#getBoundingBox
H.geo.MultiGeometry#getBounds renamed to H.geo.MultiGeometry#getBoundingBox
H.geo.MultiLineString#getBounds renamed to H.geo.MultiLineString#getBoundingBox
H.geo.Polygon#getBounds renamed to H.geo.Polygon#getBoundingBox
H.geo.MultiPolygon#getBounds renamed to H.geo.MultiPolygon#getBoundingBox
H.geo.MultiPoint#getBounds renamed to H.geo.MultiPoint#getBoundingBox

The class H.geo.Strip was deprecated in HERE Maps API for JavaScript 3.0 and removed in the new version – use H.geo.LineString instead. Respectively, the methods responsible for the calculation of the bounding box for the map objects were adjusted:

H.map.Circle#getBounds renamed to H.map.Circle#getBoundingBox
H.map.GeoShape#getBounds renamed to H.map.GeoShape#getBoundingBox
H.map.Group#getBounds renamed to H.map.Group#getBoundingBox
H.map.Overlay#getBounds renamed to H.map.Overlay#getBoundingBox
H.map.Polygon#getBounds renamed to H.map.Polygon#getBoundingBox
H.map.Polyline#getBounds renamed to H.map.Polyline#getBoundingBox
H.map.Rect#getBounds renamed to H.map.Rect#getBoundingBox
H.clustering.ICluster#getBounds renamed to H.clustering.ICluster#getBoundingBox

The map objects methods to set and get underlying geometries were changed to reflect the fact that objects could be created with different geometries. To get the geometry, changes are as follows:

H.map.AbstractMarker#getPosition renamed to H.map.AbstractMarker#getGeometry
H.map.Circle#getStrip renamed to H.map.Circle#getGeometry
H.map.DomMarker#getPosition renamed to H.map.DomMarker#getGeometry
H.map.GeoShape#getStrip renamed to H.map.GeoShape#getGeometry
H.map.Marker#getPosition renamed to H.map.Marker#getGeometry
H.map.Polygon#getStrip renamed to H.map.Polygon#getGeometry
H.map.Polyline#getStrip renamed to H.map.Polyline#getGeometry
H.map.Rect#getStrip renamed to H.map.Rect#getGeometry

And to set the geometry, changes are as follows:

H.map.AbstractMarker#setPosition renamed to H.map.AbstractMarker#setGeometry
H.map.Circle#setStrip renamed to H.map.Circle#setGeometry
H.map.DomMarker#setPosition renamed to H.map.DomMarker#setGeometry
H.map.GeoShape#setStrip renamed to H.map.GeoShape#setGeometry
H.map.Marker#setPosition renamed to H.map.Marker#setGeometry
H.map.Polygon#setStrip renamed to H.map.Polygon#setGeometry
H.map.Polyline#setStrip renamed to H.map.Polyline#setGeometry
H.map.Rect#setStrip renamed to H.map.Rect#setGeometry

Besides the above mentioned changes in the map objects' method names, all events related to them were deprecated and removed, namely:

visibilitychange
zindexchange
stylechange
stripchange

Migration to the Maps API for JavaScript 3.1

Migration to the Maps API for JavaScript 3.1

API Key Instead of "app_id" and "app_code"

Legacy Modules

WebGL as a Default Engine

Default Layers Collection

Asynchronous "getObjectAt" Interface

"LookAt" interface

Fractional Zoom Levels

"StreetLevel" and "Places" Modules

Traffic Incidents and Traffic Flow Service

Geo Shapes and Map Objects

results matching ""

No results matching ""

Developer