A comprehensive guide to migrating from Map Tile v2 to RTS v3

Introduction

Starting a blog on migrating from one technology to another can be a daunting task, especially when dealing with complex services like map tiles and rendering. In this blog post, we're embarking on a detailed journey from HERE Map Tile API version (v2) to the HERE Raster Tile API (RTS v3), which is the technology successor of Map Tile API and one of the Map Rendering Services providing the HERE base map. Please see the recommended transition paths in the table below.

The migration from Map Tile v2 to RTS v3 involves several key steps, each critical for ensuring a smooth transition and optimal utilization of the new features offered by RTS v3. These steps range from platform initialization, through tile service initialization and tile layer creation, to fine-tuning aspects such as content appearance, resource management, image formatting, and more.

This guide aims to provide a comprehensive overview of these steps, illustrated with code snippets and detailed explanations to facilitate an understanding of the changes and how to implement them effectively. Whether you are looking to update the base URL, modify resource paths, or adjust to the new parameter mappings, this guide covers all aspects of the migration process.

Furthermore, we delve into specific enhancements and new features introduced in RTS v3, such as improved language settings, pixels per inch (PPI) customization, geopolitical views, points of interest (POIs), and the handling of congestion and environmental zones. These enhancements are designed to offer developers greater control and flexibility in creating map-based applications that meet the diverse needs of their users.

Additionally, we provide insights into the Maps API for JavaScript implementation utilizing the product name and linking it. for Traffic Raster Tile API v3 and RTS v3, demonstrating how these APIs can be integrated into web applications for dynamic and interactive map rendering. Through practical examples and code snippets, readers will gain a deeper understanding of how to leverage these APIs for advanced mapping solutions.

The REST API Migration Endpoint Guide section of our blog serves as a thorough resource for developers transitioning their applications from MapTile API v2 Raster Tile API v3. It offers detailed explanations, best practices, and examples on how to update your API endpoints, ensuring a seamless migration process. This guide is particularly useful for understanding changes in endpoint URLs, request parameters, and response formats, providing the technical insights necessary for a smooth upgrade to Raster Tile API v3.

This blog is dedicated exclusively to the RTS v3 migration from MapTile v2, guiding you through the process step-by-step.

Before a deep dive into the actuals, here is a comparison between Map Tile v2, RTS v3 and the Vector Tile API:

Map Tile v2 to RTS v3 Migration Guide - Step-by-step

Platform Initialization

Map Tile v2:

Copied

        var platform = new H.service.Platform({
    apikey: api_key_developer_portal,
   
});

RTS v3:

Copied

        var platform = new H.service.Platform({
    apikey: api_key_platform_portal,
 
});

Tile Service Initialization

Map Tile v2:

Copied

        
basemaptileService = platform.getMapTileService({'type': 'base'});
aerialmaptileService = platform.getMapTileService({'type': 'aerial'});

RTS v3:

Copied

        const rasterTileService = platform.getRasterTileService({
    format: 'png',
    queryParams: {
        lang: 'en',
        ppi: 400,
        style: 'explore.day',
        features: 'pois:all,environmental_zones:all,congestion_zones:all,vehicle_restrictions:active_and_inactive'
    },
});

Tile Layer Creation

Map Tile v2:

Copied

        tileLayer = maptileService.createTileLayer(tiletype, schema, ppi ? 512 : 256, format, configObj);

RTS v3:

Please check the API reference documentation for migrating to the harp engine here, and also check how to configure the raster tile provider here.

Copied

        const rasterTileProvider = new H.service.rasterTile.Provider(rasterTileService, {
    engineType: H.Map.EngineType.HARP,
    tileSize: 512
});
const rasterTileLayer = new H.map.layer.TileLayer(rasterTileProvider);

Content and Appearance (Domain / Scheme / Style)

Map Tile v2:

Copied

        // For normal.day scheme 
var tileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8', { style: 'default' } );

RTS v3:

Copied

        // For equivalent explore.day style 
const rasterTileService = platform.getRasterTileService({ format: 'png8', queryParams: { style: 'explore.day' } });

Resource

Map Tile v2:

Copied

        // For maptile (base map tile) 
var maptileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8' );

RTS v3:

Copied

        // For base (equivalent to maptile in v2) 
const baseTileService = platform.getRasterTileService({ format: 'png8', queryParams: { resource: 'base' } });

Image Format

Map Tile v2:

Copied

        // Requesting a JPG format tile 
var jpgTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'jpg' );

RTS v3:

Copied

        // Requesting a JPEG format tile 
const jpegTileService = platform.getRasterTileService({ format: 'jpeg' });

Size

Map Tile v2:

Copied

        // Requesting a 512x512 tile 
var largeTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 512, 'png8' );

RTS v3:

Copied

        // Specifying size in RTS v3 
const largeTileService = platform.getRasterTileService({ queryParams: { size: '512' } });

Language

Map Tile v2:

Copied

        // Setting primary and secondary languages 
var bilingualTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8', { lg: 'ENG', lg2: 'FRA' } );

RTS v3:

Copied

        // Setting languages in RTS v3 
const bilingualTileService = platform.getRasterTileService({ queryParams: { lang: 'en', lang2: 'fr' } });

Pixels Per Inch (PPI)

Map Tile v2:

Copied

        // Requesting high-resolution tiles 
var highResTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8', { ppi: '320' } );

RTS v3:

Copied

        // Specifying PPI in RTS v3 
const highResTileService = platform.getRasterTileService({ queryParams: { ppi: '400' } });

Geopolitical Views

Map Tile v2:

Copied

        // Specifying a geopolitical view 
var geoViewTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8', { pview: 'ARG' } );

RTS v3:

Copied

        // Specifying geopolitical view in RTS v3 
const geoViewTileService = platform.getRasterTileService({ queryParams: { pview: 'AR' } });

Points of Interest (POIs)

Map Tile v2:

Copied

        // Enabling POIs 
var poiTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8', { pois: '1' } );

RTS v3:

Copied

        // Enabling POIs in RTS v3 
const poiTileService = platform.getRasterTileService({ queryParams: { features: 'pois:all' } });

Congestion and Environmental Zones

Map Tile v2:

Copied

        // Enabling congestion information 
var congestionTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8', { congestion: 'true' } );

RTS v3:

Copied

        // Specifying congestion & environmental zones in RTS v3 
const congestionTileService = platform.getRasterTileService({ queryParams: { features: 'environmental_zones:all,congestion_zones:all' } });

HERE Map Tile v2 (Traffic) to Traffic Raster Tile API v3- Step-by-step:

1. Base URL

Map Tile v2 (Traffic):

Copied

        let baseURL_v2 = "https://{1-4}.traffic.maps.api.here.com";

Traffic Raster Tile API v3:

Copied

        let baseURL_v3 = "https://traffic.maps.hereapi.com";

2. Version

Map Tile v2 (Traffic):

Copied

        // Included in the path 
"/maptile/2.1/flowtile/..."

Traffic Raster Tile API v3:

Copied

        // Base URL 
already specifies version

3. Resource and Path

Map Tile v2 (Traffic):

Copied

        // For flow tiles 
"/maptile/2.1/flowtile/{scheme}/{zoom}/{column}/{row}/256/png8"

Traffic Raster Tile API v3:

Copied

        // For flow tiles 
"/v3/flow/mc/{zoom}/{column}/{row}/png8?style=traffic.flow&size=256"

Request mapping

The following table details how to map a request from HERE Map Tile v2 (Traffic) to Traffic Raster Tile API:

Parameter	Here Map Tile v2 (Traffic)	HERE Traffic Raster Tile v3	Migration Notes
Base URL	{1-4}.traffic.maps.api.here.com	https://traffic.maps.hereapi.com
Version	maptile/2.1	/v3
Resource	/flowtile	/flow	For more information, see Migrate flowtile.
Resource	/flowlabeltile	-	Deprecated. For more information on how to render traffic along with labels, see Migrate Flow Label Tile.
Resource	/flowbasetile	-	Deprecated. For more information on how to render traffic along with base, see Migrate Flow Base Tile.
Resource	/traffictile	-	Deprecated. For more information on how to render traffic along with labels and base, see Migrate Traffic Tile.
Resource	/{flowtile}/{map id}/{scheme}/{zoom}/{row}/{col}/{size}/{format}	v3/flow/mc/{zoom}/{row}/{column}/{format}?style={style}&size={tile size}	scheme has been replaced by style, and style and size parameters are optional. For more information, see Mandatory Request Parameters.

Parameter Mapping

The following table details how to map parameters from HERE Map Tile v2 (Traffic) to Traffic Raster Tile API.

Traffic Raster Tile API v3	HERE Map Tile v2 (Traffic)	Migration Notes
zoom	zoom	No changes necessary.
row	row	No changes necessary.
col	column	No changes necessary.
format	format	For more information, see Result format.
map id	-	Deprecated.
scheme	style	Now a query parameter, and supported styles have changed. For more information, see Set the Style.
size	size	Now a query parameter, and supported sizes have changed. For more information, see Change the Image Size.
app_id	-	Deprecated. For more information, see Authentication.
app_code	-	Deprecated. For more information, see Authentication.
time	-	Deprecated.
ppi	ppi	Supported PPI has changed. For more information, see Change the PPI.
range	-	Deprecated.
style	style	For more information, see Set the Style.
min_traffic_congestion	minTrafficCongestion	For more information, see Apply the Traffic Congestion Filter.

JavaScript Implementation for RTS v3

Copied

        <!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=yes">
    <meta http-equiv="Content-type" content="text/html;charset=UTF-8">
    <link rel="stylesheet" type="text/css" href="https://js.api.here.com/v3/3.1/mapsjs-ui.css" />
    <script type="text/javascript" src="https://js.api.here.com/v3/3.1/mapsjs-core.js"></script>
    <script type="text/javascript" src="https://js.api.here.com/v3/3.1/mapsjs-service.js"></script>
    <script type="text/javascript" src="https://js.api.here.com/v3/3.1/mapsjs-ui.js"></script>
    <script type="text/javascript" src="https://js.api.here.com/v3/3.1/mapsjs-mapevents.js"></script>
	<script type="text/javascript" src="https://js.api.here.com/v3/3.1/mapsjs-harp.js"></script>
  <style>
  #map {
      width: 100%;
      height: 480px;
      background: grey;
  }

  #panel {
      width: 100%;
      height: 400px;
  }
  </style>
  </head>

  <div id="map"/> </div>

  	<script type="text/javascript" >

    var platform = new H.service.Platform({
      apikey: "your-platform-key"
    });

    var defaultLayers = platform.createDefaultLayers();
    var engineType = H.Map.EngineType['HARP'];
    var defaultLayers = platform.createDefaultLayers({
    	engineType: engineType,
      pois: true,
      tileSize: devicePixelRatio > 1 ? 512 : 256,
      ppi: devicePixelRatio > 1 ? 320 : 72,
    });


    const rasterTileService = platform.getRasterTileService({
      queryParams: {
      lang: 'en',
      lang2:'th',
      ppi: 400,
      style: 'explore.day',
      features: 'pois:all,environmental_zones:all,congestion_zones:all',
      size: '256'
      },
    });

    const rasterTileProvider = new H.service.rasterTile.Provider(rasterTileService, {
        engineType: H.Map.EngineType.HARP,
        tileSize: 512
    });

    const rasterTileLayer = new H.map.layer.TileLayer(rasterTileProvider);


    //Step 2: initialize a map - this map is centered over Europe
    var map = new H.Map(document.getElementById('map'),
      rasterTileLayer,{
      center: {lat:52.51604, lng: 13.37691},
      zoom: 15,
      engineType: H.Map.EngineType['HARP'],
      pixelRatio: window.devicePixelRatio || 1,
      tileSize: 512
    });

    // add a resize listener to make sure that the map occupies the whole container
    window.addEventListener('resize', () => map.getViewPort().resize());

    // Behavior implements default interactions for pan/zoom (also on mobile touch environments)
    var behavior = new H.mapevents.Behavior(new H.mapevents.MapEvents(map));

    // Create the default UI components
    var ui = H.ui.UI.createDefault(map, defaultLayers);
   // remove existing uiSettings
    ui.removeControl("mapsettings");
    const scalebar = ui.getControl('scalebar');
    ui.removeControl('scalebar');

    // create custom one
    var ms = new H.ui.MapSettingsControl( {
       baseLayers : [ {
         label:"normal",layer:defaultLayers.raster.normal.map
       },
       {
         label:"satellite",layer:defaultLayers.raster.satellite.map
       }
       ]
     });

    ui.addControl("customized",ms);
    ui.addControl('scalebar', scalebar);

    </script>
  </body>
</html>

JavaScript implementation for Traffic Map Tile API v2 and other parameters can be found here.

In Closing:

The HERE Raster Tile API v3 is a REST API that allows you to request map tile images for all regions in the world. These map tiles, when combined in a grid, form a complete map of the world. This is the replacement service for the HERE Map Tile API v2 service. It's important to note that the migration to HERE Raster Tile API v3 is not just a technical upgrade; it's an opportunity to enhance the user experience, leverage more detailed and accurate map data, and explore new possibilities in the realm of digital mapping. Stay tuned for our next blog post, which will explore the transition to the HERE Vector Tile API, offering insights into interactivity, client-side rendering, customization (using HERE Style Editor), and 3D views. Join us on this exciting journey through the world of map-based services and discover how to navigate the migration process with ease and confidence.

Sachin Jonda

Lead Onboarding Engineer

Have your say

Sign up for our newsletter

Why sign up:

Latest offers and discounts
Tailored content delivered weekly
Exclusive events
One click to unsubscribe

A comprehensive guide to migrating from Map Tile v2 to RTS v3

Introduction

Map Tile v2 to RTS v3 Migration Guide - Step-by-step

Platform Initialization

Tile Service Initialization

Tile Layer Creation

Content and Appearance (Domain / Scheme / Style)

Resource

Image Format

Size

Language

Pixels Per Inch (PPI)

Geopolitical Views

Points of Interest (POIs)

Congestion and Environmental Zones

HERE Map Tile v2 (Traffic) to Traffic Raster Tile API v3- Step-by-step:

1. Base URL

2. Version

3. Resource and Path

Request mapping

Parameter Mapping

JavaScript Implementation for RTS v3

In Closing:

Sachin Jonda

Have your say

Related articles

Interactive Geofencing and Location Search with HERE Maps API for JavaScript

WKT for what? A deeper dive into Well-Known Text format for API calls & testing

All about Markers in the HERE Maps API for JavaScript

Sign up for our newsletter