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:
var platform = new H.service.Platform({
apikey: api_key_developer_portal,
});
RTS v3:
var platform = new H.service.Platform({
apikey: api_key_platform_portal,
});
Tile Service Initialization
Map Tile v2:
basemaptileService = platform.getMapTileService({'type': 'base'});
aerialmaptileService = platform.getMapTileService({'type': 'aerial'});
RTS v3:
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:
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.
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:
// For normal.day scheme
var tileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8', { style: 'default' } );
RTS v3:
// For equivalent explore.day style
const rasterTileService = platform.getRasterTileService({ format: 'png8', queryParams: { style: 'explore.day' } });
Resource
Map Tile v2:
// For maptile (base map tile)
var maptileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8' );
RTS v3:
// For base (equivalent to maptile in v2)
const baseTileService = platform.getRasterTileService({ format: 'png8', queryParams: { resource: 'base' } });
Image Format
Map Tile v2:
// Requesting a JPG format tile
var jpgTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'jpg' );
RTS v3:
// Requesting a JPEG format tile
const jpegTileService = platform.getRasterTileService({ format: 'jpeg' });
Size
Map Tile v2:
// Requesting a 512x512 tile
var largeTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 512, 'png8' );
RTS v3:
// Specifying size in RTS v3
const largeTileService = platform.getRasterTileService({ queryParams: { size: '512' } });
Language
Map Tile v2:
// Setting primary and secondary languages
var bilingualTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8', { lg: 'ENG', lg2: 'FRA' } );
RTS v3:
// Setting languages in RTS v3
const bilingualTileService = platform.getRasterTileService({ queryParams: { lang: 'en', lang2: 'fr' } });
Pixels Per Inch (PPI)
Map Tile v2:
// Requesting high-resolution tiles
var highResTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8', { ppi: '320' } );
RTS v3:
// Specifying PPI in RTS v3
const highResTileService = platform.getRasterTileService({ queryParams: { ppi: '400' } });
Geopolitical Views
Map Tile v2:
// Specifying a geopolitical view
var geoViewTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8', { pview: 'ARG' } );
RTS v3:
// Specifying geopolitical view in RTS v3
const geoViewTileService = platform.getRasterTileService({ queryParams: { pview: 'AR' } });
Points of Interest (POIs)
Map Tile v2:
// Enabling POIs
var poiTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8', { pois: '1' } );
RTS v3:
// Enabling POIs in RTS v3
const poiTileService = platform.getRasterTileService({ queryParams: { features: 'pois:all' } });
Congestion and Environmental Zones
Map Tile v2:
// Enabling congestion information
var congestionTileLayer = platform.getMapTileService({ type: 'base' }).createTileLayer( 'maptile', 'normal.day', 256, 'png8', { congestion: 'true' } );
RTS v3:
// 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):
let baseURL_v2 = "https://{1-4}.traffic.maps.api.here.com";
Traffic Raster Tile API v3:
let baseURL_v3 = "https://traffic.maps.hereapi.com";
2. Version
Map Tile v2 (Traffic):
// Included in the path
"/maptile/2.1/flowtile/..."
Traffic Raster Tile API v3:
// Base URL
already specifies version
3. Resource and Path
Map Tile v2 (Traffic):
// For flow tiles
"/maptile/2.1/flowtile/{scheme}/{zoom}/{column}/{row}/256/png8"
Traffic Raster Tile API v3:
// 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
<!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.
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