Migration from MapTile v2 to Raster Tile v3

Applies To:
-----------

HERE Maps API for JavaScript 3.1.x
Raster Tile API v3
Legacy Map Tile API v2 integrations
HARP rendering engine deployments



Symptoms / Triggers:
--------------------

Customers may report one or more of the following:

Map tiles do not appear after upgrading HERE JavaScript SDK.
Existing map initialization code using getMapTileService() no longer produces expected map rendering.
Legacy MapTile v2 implementations stop receiving updates or are no longer recommended.
Hybrid or satellite layers cannot be initialized using previous MapTile v2 code.
Application migration projects require replacement of deprecated tile services.
Developers observe that layers created using: platform.getMapTileService()

must be replaced with newer raster tile implementations.



Summary:
--------

Legacy implementations using HERE Map Tile API v2 should be migrated to Raster Tile API v3. The recommended solution is to replace platform.getMapTileService() based layers with layers created through platform.getRasterTileService() and update map initialization accordingly.



Answer:
-------

Map Tile API v2 has been deprecated and customers should migrate to Raster Tile API v3 where applicable. Existing applications that rely on getMapTileService() should be updated to use getRasterTileService() and modern tile layer creation methods.

Example legacy implementation:

var mapTiler = platform.getMapTileService({type:'base'});

var tileLayer = mapTiler.createTileLayer(

'maptile',

'hybrid.day',

256,

'jpg'

);

map.setBaseLayer(tileLayer);

Example migration approach:

const rasterTileService = platform.getRasterTileService({<br /><br />queryParams:{<br /><br />style:'explore.day'<br /><br />}<br /><br />});

const rasterTileProvider = new H.service.rasterTile.Provider(

rasterTileService,

{<br /><br />engineType:H.Map.EngineType.HARP,<br /><br />tileSize:512<br /><br />}

);

const rasterTileLayer = new H.map.layer.TileLayer(

rasterTileProvider

);



Root Cause:
-----------

The application is using a legacy map tile service implementation based on Map Tile API v2.

As HERE platform services evolved, Raster Tile API v3 became the recommended replacement for raster map tile delivery and styling capabilities.

Applications that continue using legacy map tile initialization patterns may require code updates to align with supported services and SDK capabilities.



Impact:
-------

### What Continues to Work

Standard JavaScript Maps API applications.
Applications migrated to Raster Tile API v3.
Supported raster styles such as Explore variants.
Supported HARP engine deployments.

### What May Be Affected

Legacy MapTile v2 implementations.
Older initialization examples copied from historical projects.
Applications using deprecated tile layer creation patterns.



Recommended Actions:
--------------------

### Migration Procedure

1. Locate all uses of: platform.getMapTileService()
2. Replace them with: platform.getRasterTileService()
3. Create a Raster Tile Provider: new H.service.rasterTile.Provider(...)
4. Create the corresponding tile layer: new H.map.layer.TileLayer(...)
5. Validate map rendering, layer switching, language settings, and tile styling.

### Validation Checklist

Base map renders successfully.
Zoom levels load correctly.
Satellite/hybrid layers render as expected.
Language parameters return localized labels.
No tile-loading errors appear in browser developer tools.

### Escalation Guidance

Escalate only if:

Raster Tile API v3 tiles do not render.
Authentication succeeds but tiles fail to load.
Supported styles return unexpected results.
Migration cannot reproduce behavior previously achieved with supported APIs.



Expected vs Unexpected Behavior
-------------------------------

| Expected Behavior | Unexpected Behavior |
| --- | --- |
| Raster Tile API v3 tiles render successfully | No map tiles displayed |
| Base map loads after migration | Blank map displayed |
| Supported styles load correctly | Unsupported style definitions fail |
| Tile layer initialization succeeds | Tile provider initialization errors |
| Localized map labels are displayed when configured | Missing or inconsistent localization |



Notes:
------

Customers should avoid creating new implementations based on Map Tile API v2.
Migration projects should validate rendering behavior across supported browsers.
SDK version applicability should be verified during upgrade projects.
Raster Tile API v3 should be considered the preferred migration target for raster map rendering use cases.



Reference Info or Doc and Their Links:
--------------------------------------

1. HERE Maps API for JavaScript Documentation
2. Raster Tile API Documentation
3. HERE Maps API for JavaScript API Reference
4. Map Styles Documentation
5. Platform Overview

Keywords or Tags:
-----------------

map tiles not loading
blank map
MapTile v2
Raster Tile API v3
HERE Maps API
JavaScript SDK
getMapTileService
getRasterTileService
HARP engine
map migration
tile layer
hybrid day
explore day
raster tiles
* deprecated API